path: root/doc/mason-lspconfig.txt

*mason-lspconfig.nvim*

Minimum version of neovim: 0.7.0

Author: William Boman
                                       Type |gO| to see the table of contents.

==============================================================================
INTRODUCTION                                    *mason-lspconfig-introduction*

`mason-lspconfig.nvim` closes some gaps that exist between `mason.nvim` and
`lspconfig`. Its main responsibilities are to:

-   register a setup hook with `lspconfig` that ensures servers installed with
    `mason.nvim` are set up with the necessary configuration
-   provide extra convenience APIs such as the `:LspInstall` command
-   allow you to (i) automatically install, and (ii) automatically set up a
    predefined list of servers
-   translate between `lspconfig` server names and `mason.nvim` package names
    (e.g. `lua_ls <-> lua-language-server`)

It is recommended to use this extension if you use `mason.nvim` and
`lspconfig` (it's strongly recommended for Windows users).

Note: ~
    This plugin uses the `lspconfig` server names in the APIs it exposes - not
    `mason.nvim` package names. See these tables for a complete mapping:
    - :h |mason-lspconfig-server-map|
    - https://github.com/williamboman/mason-lspconfig.nvim/blob/main/doc/server-mapping.md

==============================================================================
REQUIREMENTS                                    *mason-lspconfig-requirements*

`mason-lspconfig` requires `mason.nvim` & `lspconfig` to be installed.
Note that `lspconfig` needs to be available in |rtp| by the time you set up
`mason-lspconfig`.

Make sure to set up `mason` and `mason-lspconfig.nvim` before setting up
servers via `lspconfig`.

==============================================================================
QUICK START                                       *mason-lspconfig-quickstart*

-----------------
Setting up mason-lspconfig.nvim

It's important that you set up the plugins in the following order:

1. `mason.nvim`
2. `mason-lspconfig.nvim`
3. Setup servers via `lspconfig`

Note: ~
    `lspconfig` needs to be available in |rtp| so that `mason-lspconfig` can
    successfully call `require("lspconfig")` (|lua-require|) during setup.
    Pay extra attention to this if you lazy-load plugins, or somehow "chain"
    the loading of plugins via your plugin manager.

To enable the `mason-lspconfig` plugin, call the `setup()` function, like so:
>lua
    require("mason").setup()
    require("mason-lspconfig").setup()
<
Refer to |mason-lspconfig-settings| for available settings.

-----------------
Setting up servers

Next, you're ready to set up the servers you want to use. Refer to lspconfig's
documentation |lspconfig-quickstart| for more information on how to do so!
>lua
    require("lspconfig").lua_ls.setup {}
    require("lspconfig").rust_analyzer.setup {}
<
Automatic server setup (advanced feature): ~
    Refer to |mason-lspconfig-dynamic-server-setup| (advanced feature) for an
    alternative method of setting up servers that doesn't require you to
    imperatively set up each server one by one.

-----------------
Installation of servers

To install an LSP server supported by lspconfig (and mason.nvim) you may use
the `:LspInstall` command, like so:
>vim
    :LspInstall rust_analyzer lua_ls
<
This command is more or less an alias of the |:MasonInstall| command, except
that it only accepts LSP servers and - more importantly - only accepts
lspconfig server names (as opposed to mason.nvim package names).

You may also run the same command without any arguments. This will prompt you
with a selection of servers that are recommended for the filetype of the
buffer you're currently editing:
>vim
    :LspInstall
<
==============================================================================
COMMANDS                                            *mason-lspconfig-commands*

------------------------------------------------------------------------------
INSTALLING AN LSP SERVER
                                                                 *:LspInstall*
>vim
:LspInstall [<server>...]
<
Installs the provided servers. This command only accepts servers that have a
corresponding server configuration in `lspconfig`.

You may also provide a language, like `:LspInstall typescript`. This will
prompt you with a selection of all available servers for that given language.

When the command is ran without any arguments, the currently active buffer's
'filetype' will be used to identify relevant servers, and you will be prompted
with a selection of all suggested servers.

------------------------------------------------------------------------------
UNINSTALLING AN LSP SERVER
                                                               *:LspUninstall*
>vim
:LspUninstall <server> ...
<
Uninstalls the provided servers.

==============================================================================
SETTINGS                                            *mason-lspconfig-settings*

You can configure certain behavior of `mason-lspconfig` when calling the
`.setup()` function.

Refer to |mason-lspconfig-default-settings| for all available settings.

Example:
>lua
    require("mason-lspconfig").setup({
        ensure_installed = { "rust_analyzer", "tsserver" }
    })
<
                                            *mason-lspconfig-default-settings*
>lua
    local DEFAULT_SETTINGS = {
        -- A list of servers to automatically install if they're not already installed. Example: { "rust_analyzer@nightly", "lua_ls" }
        -- This setting has no relation with the `automatic_installation` setting.
        ---@type string[]
        ensure_installed = {},

        -- Whether servers that are set up (via lspconfig) should be automatically installed if they're not already installed.
        -- This setting has no relation with the `ensure_installed` setting.
        -- Can either be:
        --   - false: Servers are not automatically installed.
        --   - true: All servers set up via lspconfig are automatically installed.
        --   - { exclude: string[] }: All servers set up via lspconfig, except the ones provided in the list, are automatically installed.
        --       Example: automatic_installation = { exclude = { "rust_analyzer", "solargraph" } }
        ---@type boolean
        automatic_installation = false,

        -- See `:h mason-lspconfig.setup_handlers()`
        ---@type table<string, fun(server_name: string)>?
        handlers = nil,
    }
<

==============================================================================
AUTOMATIC SERVER SETUP                *mason-lspconfig-automatic-server-setup*
                                        *mason-lspconfig-dynamic-server-setup*


`mason-lspconfig` provides extra, opt-in, functionality that allows you to
automatically set up LSP servers installed via `mason.nvim` without having to
manually add each server setup to your Neovim configuration. It also makes it
possible to use newly installed servers without having to restart Neovim!

Example:
>lua
    require("mason").setup()
    require("mason-lspconfig").setup()

    require("mason-lspconfig").setup_handlers {
        -- The first entry (without a key) will be the default handler
        -- and will be called for each installed server that doesn't have
        -- a dedicated handler.
        function (server_name) -- default handler (optional)
            require("lspconfig")[server_name].setup {}
        end,
        -- Next, you can provide a dedicated handler for specific servers.
        -- For example, a handler override for the `rust_analyzer`:
        ["rust_analyzer"] = function ()
            require("rust-tools").setup {}
        end
    }
<
Note: ~
    If you use this approach, make sure you don't also manually set up servers
    directly via `lspconfig` as this will cause servers to be set up more than
    once.

Refer to |mason-lspconfig.setup_handlers()| for more information.

==============================================================================
Lua module: mason-lspconfig

                                                     *mason-lspconfig.setup()*
setup({config})
    Sets up mason with the provided {config} (see |mason-lspconfig-settings|).

                                            *mason-lspconfig.setup_handlers()*
setup_handlers({handlers})
    Advanced feature ~
        This is an advanced, opt-in, feature that requires some careful
        reading of the documentation.

        The recommended method to set up servers with lspconfig is to do so by
        following their guides, see |lspconfig-quickstart|.

    Registers the provided {handlers}, to be called by mason when an installed
    server supported by lspconfig is ready to be set up.

    When this function is called, all servers that are currently installed
    will be considered ready to be set up. When a new server is installed
    during a session, it will be considered ready to be set up when
    installation succeeds.

    {handlers} is a table where the keys are the name of an lspconfig server,
    and the values are the function to be called when that server is ready to
    be set up (i.e. is installed).

    You may also pass a default handler that will be called when no dedicated
    handler is provided. This is done by providing a function without a key
    (see example below).

   Note: ~
       The server names provided as keys are the lspconfig server names, not
       mason's package names, so for example instead of "lua-language-server"
       it's "lua_ls".

   Example: ~
>lua
       local handlers = {
           -- The first entry (without a key) will be the default handler
           -- and will be called for each installed server that doesn't have
           -- a dedicated handler.
           function (server_name) -- default handler (optional)
               require("lspconfig")[server_name].setup {}
           end,
           -- Next, you can provide targeted overrides for specific servers.
           ["rust_analyzer"] = function ()
               require("rust-tools").setup {}
           end,
           ["lua_ls"] = function ()
               local lspconfig = require("lspconfig")
               lspconfig.lua_ls.setup {
                   settings = {
                       Lua = {
                           diagnostics = {
                               globals = { "vim" }
                           }
                       }
                   }
               }
           end,
       }

       -- alt 1. Either pass handlers when setting up mason-lspconfig:
       require("mason-lspconfig").setup({ handlers = handlers })

       -- alt 2. or call the .setup_handlers() function.
       require("mason-lspconfig").setup_handlers(handlers)
<

    See also: ~
        You may achieve similar behaviour by manually looping through the
        installed servers (see |mason-lspconfig.get_installed_servers()|) and
        setting each one up.

                                     *mason-lspconfig.get_installed_servers()*
get_installed_servers()
    Returns the installed LSP servers supported by lspconfig.

    Note: ~
        The returned strings are the lspconfig server names, not the mason
        package names. For example, "lua_ls" is returned instead of
        "lua-language-server". This is useful if you want to loop through the
        table and use its values to directly interact with lspconfig (for
        example setting up all installed servers).

    Returns: ~
        string[]

    See also: ~
        |mason-registry.get_installed_packages()|
        |mason-registry.get_installed_package_names()|

                                     *mason-lspconfig.get_available_servers()*
get_available_servers({filter})
    Returns the available (both installed & uninstalled) LSP servers.

    Note: ~
        The returned strings are the lspconfig server names, not the mason
        package names. For example, "lua_ls" is returned instead of
        "lua-language-server". This is useful if you want to loop through the
        table and use its values to directly interact with lspconfig (for
        example setting up all installed servers).

    Parameters: ~
        {filter}  (table|nil) A table with key-value pairs used to
                  filter the list of server names. The available keys are:
                  - filetype (string | string[]): Only return servers with
                    matching filetype

    Returns: ~
        string[]

    See also: ~
        |mason-registry.get_all_packages()|
        |mason-registry.get_all_package_names()|

                                              *mason-lspconfig.get_mappings()*
get_mappings()
    Returns the server name mappings between lspconfig and Mason.

    Returns: ~
        {
            lspconfig_to_mason: table<string, string>,
            mason_to_lspconfig: table<string, string>
        }

 vim:tw=78:ft=help:norl:expandtab:sw=4