nvim-lsp

Collection of common configurations for the Nvim LSP client.

It is hoped that these configurations serve as a "source of truth", but they are strictly best effort. If something doesn't work, these configs are useful as a starting point, which you can adjust to fit your environment.

This is work-in-progress and requires Nvim HEAD/nightly. Update Nvim and nvim-lsp before reporting an issue.

Contributions are welcome!

There are many language servers in the world, and not enough time. Help us create configs for all the LSPs!

Read CONTRIBUTING.md for instructions. Ask questions in Neovim Gitter.
Choose a language from the coc.nvim wiki or the emacs-lsp project.
Create a new file at lua/nvim_lsp/SERVER_NAME.lua. See existing configs for examples (lua/nvim_lsp/texlab.lua is an extensive example).

Install

Requires Nvim HEAD/nightly (v0.5 prerelease).
nvim-lsp is just a plugin. Install it like any other Vim plugin.
```
:Plug 'neovim/nvim-lsp'
```

Usage

Each config provides a setup() function, to initialize the server with reasonable defaults and some server-specific things like commands or different diagnostics.

require'nvim_lsp'.<config>.setup{name=…, settings = {…}, …}

Find the config for your language, then paste the example given there to your init.vim. All examples are given in Lua, see :help :lua-heredoc to use Lua from your init.vim.

Some configs may define additional server-specific functions, e.g. the texlab config provides nvim_lsp.texlab.buf_build({bufnr}).

Example: using the defaults

To use the defaults, just call setup() with an empty config parameter. For the gopls config, that would be:

require'nvim_lsp'.gopls.setup{}

Example: override some defaults

To set some config properties at setup(), specify their keys. For example to change how the "project root" is found, set the root_dir key:

local nvim_lsp = require'nvim_lsp'
nvim_lsp.gopls.setup{
  root_dir = nvim_lsp.util.root_pattern('.git');
}

The documentation for each config lists default values and additional optional properties.

local nvim_lsp = require'nvim_lsp'
nvim_lsp.texlab.setup{
  name = 'texlab_fancy';
  log_level = vim.lsp.protocol.MessageType.Log;
  settings = {
    latex = {
      build = {
        onSave = true;
      }
    }
  }
}

Example: custom config

To configure a custom/private server, just require nvim_lsp/skeleton and do the same as we do if we were adding it to the repository itself.

Define the config: configs.foo_lsp = { … }
Call setup(): require'nvim_lsp'.foo_lsp.setup{}

local nvim_lsp = require'nvim_lsp'
local configs = require'nvim_lsp/skeleton'
-- Check if it's already defined for when I reload this file.
if not nvim_lsp.foo_lsp then
  configs.foo_lsp = {
    default_config = {
      cmd = {'/home/ashkan/works/3rd/lua-language-server/run.sh'};
      filetypes = {'lua'};
      root_dir = function(fname)
        return nvim_lsp.util.find_git_ancestor(fname) or vim.loop.os_homedir()
      end;
      log_level = vim.lsp.protocol.MessageType.Warning;
      settings = {};
    };
  }
end
nvim_lsp.foo_lsp.setup{}

Installing a language server

Configs may provide an install() function. Then you can use :LspInstall {name} to install the required language server. For example, to install the Elm language server:

:LspInstall elmls

Use :LspInstallInfo to see install info.

:LspInstallInfo

setup() function

The setup() interface:

nvim_lsp.SERVER.setup{config}

  The `config` parameter has the same shape as that of
  |vim.lsp.start_client()|, with these additions and changes:

  {root_dir}
    Required for some servers, optional for others.
    Function of the form `function(filename, bufnr)`.
    Called on new candidate buffers being attached-to.
    Returns either a root_dir or nil.

    If a root_dir is returned, then this file will also be attached. You
    can optionally use {filetype} to help pre-filter by filetype.

    If a root_dir is returned which is unique from any previously returned
    root_dir, a new server will be spawned with that root_dir.

    If nil is returned, the buffer is skipped.

    See |nvim_lsp.util.search_ancestors()| and the functions which use it:
    - |nvim_lsp.util.root_pattern(patterns...)| finds an ancestor which
    - contains one of the files in `patterns...`. This is equivalent
      to coc.nvim's "rootPatterns"
    - Related utilities for common tools:
      - |nvim_lsp.util.find_git_root()|
      - |nvim_lsp.util.find_node_modules_root()|
      - |nvim_lsp.util.find_package_json_root()|

  {name}
    Defaults to the server's name.

  {filetypes}
    Set of filetypes to filter for consideration by {root_dir}.
    May be empty.
    Server may specify a default value.

  {log_level}
    controls the level of logs to show from build processes and other
    window/logMessage events. Defaults to
    vim.lsp.protocol.MessageType.Warning instead of
    vim.lsp.protocol.MessageType.Log.

  {settings}
    Map with case-sensitive keys corresponding to `workspace/configuration`
    event responses.
    We also notify the server *once* on `initialize` with
    `workspace/didChangeConfiguration`.
    If you change the settings later on, you must emit the notification
    with `client.workspace_did_change_configuration({settings})`
    Example: `settings = { keyName = { subKey = 1 } }`

  {on_attach}
    `function(client)` executed with the current buffer as the one the {client}
    is being attached-to. This is different from
    |vim.lsp.start_client()|'s on_attach parameter, which passes the {bufnr} as
    the second parameter instead. Useful for doing buffer-local setup.

  {on_new_config}
    `function(new_config)` will be executed after a new configuration has been
    created as a result of {root_dir} returning a unique value. You can use this
    as an opportunity to further modify the new_config or use it before it is
    sent to |vim.lsp.start_client()|.

Configurations

The following LSP configs are included. Follow a link to find documentation for that config.

6.5 KiB Raw Blame History