Configuration File

⚠️Warning

This wiki has been replaced by the wiki on our website. This wiki will be removed in the future.

The Configuration File

There are multiple ways to provide a configuration file to customize how the language server operates. A full list of the available configuration settings can be found on the settings page.

The 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 from VS Code)

JSON Schema

A JSON schema is available in multiple languages to help make the creation of a JSON configuration file easier.

In VS Code, this schema is already injected into .vscode/settings.json and .luarc.json but for other editors where this is not the case, it can be added manually by adding the following to the start of your JSON file:

{
"$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json"
}

Visual Studio Code

In Visual Studio Code, you can use the settings UI or write directly to the settings.json file. You can also use a .luarc.json file.

The settings.json file can be found in the following OS-dependent locations:

OS	Path
Windows	%APPDATA%\Code\User\settings.json
Linux	$HOME/.config/Code/User/settings.json
MacOS	$HOME/Library/Application\ Support/Code/User/settings.json

You can also define your settings on a workspace-specific basis, which can help improve speeds and is recommended for project-specific settings.

For more details, read the VS Code documentation.

.luarc.json

A .luarc.json file can be added to your workspace to apply a certain configuration to the server. This file must be written in JSON and can use the same JSON schema and settings as the other configuration files - which is highly recommended.

Note: The Lua. prefix for settings is not necessary in a .luarc.json file!

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

{
"workspace.library": ["path/to/library/directory"],
"runtime.version": "Lua 5.3",
"hint.enable": false
}

Custom Config File

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 Lua or JSON.

This file can then be loaded by using the --configpath flag.

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
}
}

Other Clients

Each client may handle the configuration file differently, below are some examples of how to get going with other clients.

Neovim with built-in LSP client

This guide assumes that you are already familiar with how the built-in client works.

Settings are defined as a nested Lua table, like so:

require'lspconfig'.sumneko_lua.setup {
settings= {
-- Settings go here!
}
}

Because the settings must be a nested table, this means when you see "Lua.runtime.version": "5.3" in the JSON schema, you must write:

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

Here is an example configuration file that can be used when writing standalone Lua scripts with luarocks libraries:

-- You will have to adjust your values according to your systemsettings= {
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'
}
}
}
}

ℹ️ Notice that we are able to execute Lua like vim.fn.expand to dynamically build the correct value.

Neovim with coc.nvim

Thanks to gustavo-hms

1. Execute :CocConfig;
2. A JSON file will open
3. Write your settings in the opened JSON file

Example

{
// ... many unrelated options here ..."languageserver": {
"lua": {
"cwd": "full path of lua-language-server directory", // (not sure this one is really necessary)"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"
}
}
}
}

Kakoune with kak-lsp

Make sure you have kak-lsp installed.

Installation

If using plug.kak, place the following in your kakrc:

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

If running standalone, place the kak-lsp binary on your PATH and then place the following in your kakrc:

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

Initialization

Place the following in your kakrc:

# 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

And the below in your kak-lsp.toml to inform it of the existence of the language server:

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

Configuration

To define server settings, place them under [language.lua.settings] in your kak-lsp.toml:

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