Configuration

The language server is highly configurable. You can view all of the settings in this wiki or in the JSON schema , which is available in multiple languages.

The language server loads its settings from one of the following sources, in order of priority:

1. The file specified by --configpath.
2. A .luarc.json file in the workspace.
3. The configuration file sent from the LSP client (like settings.json from VS Code).

There are three kinds of configuration files that can be used:

• LSP client-specific configuration file.
  • This is a configuration file that usually lives in your editor, like the settings.json file from VS Code. It is usually the easiest to use as the clients usually have their own tools for these.
• A .luarc.json file (recommended).
  • This file can be used between different clients/editors.
• A custom configuration file
  • A file of your choice written in either Lua or JSON.

Each client has their own specific method for configuring the language server. We go through some popular clients below:

Make sure you take note of whether you are editing your user-wide or workspace settings . Some settings you may want to always be in effect, these should be user settings. Other settings like workspace.library should be workspace only.

1. Press Ctrl + , to open the settings page
2. Enter @ext:sumneko.lua in the search bar
3. Configure away!

Below are some examples for getting set up in Neovim in different environments.

require'lspconfig'.lua_ls.setup{
  settings = {
    Lua = {
      runtime = {
        version = "LuaJIT"
      }
    }
  }
}

require'lspconfig'.lua_ls.setup{
  settings = {
    Lua = {
      runtime = {
        version = 'Lua 5.3',
        path = {
          '?.lua',
          '?/init.lua',
          vim.fn.expand'~/.luarocks/share/lua/5.3/?.lua',
          vim.fn.expand'~/.luarocks/share/lua/5.3/?/init.lua',
          '/usr/share/5.3/?.lua',
          '/usr/share/lua/5.3/?/init.lua'
        }
      },
      workspace = {
        library = {
          vim.fn.expand'~/.luarocks/share/lua/5.3',
          '/usr/share/lua/5.3'
        }
      }
    }
  }
}

{
  // Unrelated settings...
  "languageserver": {
    "lua": {
      "cwd": "full path to lua-language-server directory",
      "command": "full path to lua-language-server executable",
      "filetypes": ["lua"],
      "rootPatterns": [".git/"]
    }
  },
  "settings": {
    "Lua": {
      "workspace": {
        "library": [
          "/path/to/hammerspoon-completion/build/stubs",
          "/path/to/neovim/runtime/lua"
        ],
        "maxPreload": 2000,
        "preloadFileSize": 1000
      },
      "runtime": {
        "version": "Lua 5.4"
      },
      "diagnostics": {
        "enable": true,
        "globals": ["hs", "vim", "it", "describe", "before_each", "after_each"],
        "disable": ["lowercase-global"]
      },
      "completion": {
        "keywordSnippet": "Disable"
      }
    }
  }
}

plug "kak-lsp/kak-lsp" do %{ cargo install --locked --force --path . }

evaluate-commands %sh{
  kak-lsp --kakoune -s $kak_session
}

## Enable kak-lsp for Lua files
hook global WinSetOption filetype=lua %{
    lsp-enable-window
}
## Close kak-lsp when kakoune is terminated
hook global KakEnd .* lsp-exit

[language.lua]
filetypes = ["lua"]
roots = [".git/"]
command = "lua-language-server"

[language.lua.settings]
Lua.diagnostics.severity = { undefined-global = "Error" }
Lua.runtime.version = "Lua 5.2"
Lua.telemetry.enable = false

A .luarc.json file can be added to your workspace to apply a certain configuration to the server.

It is recommended you use a JSON schema to receive completion and validation, if your editor supports it. In VS Code, the schema is already injected into .vscode/settings.json and .luarc.json files.

Here is a basic example of a .luarc.json file:

{
  "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
  "workspace.library": ["path/to/library/directory"],
  "runtime.version": "Lua 5.3",
  "hint.enable": false
}

If you want to use your own custom configuration file, with whatever name you please, that is also an option, although it must be written in either Lua or JSON. This file can then be loaded by using the --configpath flag.

If writing the file in JSON, it should be formatted like a .luarc.json file.

If writing the file in Lua, the configuration file can consist of nested tables;

return {
    Lua = {
        runtime = {
            version = "Lua 5.1"
        }
    }
}

keys;

return {
    ["Lua.runtime.version"] = "Lua 5.1"
}

or even a combination of both!

return {
    Lua = {
        runtime = {
            version = "Lua 5.1"
        },
        ["completion.enable"] = false
    }
}