Skip to content
AstroNvim Documentation

Advanced LSP Setup

LSP configuration is mostly done through the help of AstroLSP, the AstroNvim language server configuration engine plugin. This provides a simple to use interface for configuration while handling the complex integration between the AstroNvim features, nvim-lspconfig, mason.nvim and mason related tooling, and none-ls.nvim. For full documentation on how to use and configure this plugin you can check out the plugin’s README or run :h astrolsp in AstroNvim. All of the following recipes are provided through lazy.nvim plugin specifications and can be added to your own plugins.

Configuring Language Servers

Our main tool for configuring and setting up language servers is with the nvim-lspconfig plugin. This plugin provides configurations for many common language servers (A full list can be found in nvim-lspconfig server configurations documentation). These baseline configuration options are not always sufficient to meet everyone’s needs, and are typically configured by calling require("lspconfig")[<server_name>].setup(opts) where opts is a table of options. For the complete set of options that can be used in the nvim-lspconfig setup check out :h lspconfig-setup in your editor.

AstroLSP automatically calls these setup functions for language servers installed through Mason and for servers specified manually (See LSP Setup Without Installer). AstroLSP also provides a simple config table in the plugin’s options for extending the built in server configurations provided by nvim-lspconfig.

lua/plugins/astrolsp.lua
return {
  "AstroNvim/astrolsp",
  ---@type AstroLSPOpts
  opts = {
    config = {
      -- the key is the server name to configure
      -- the value is the configuration table
      clangd = {
        capabilities = {
          offsetEncoding = "utf-8",
        },
      },
    },
  },
}

Custom LSP Definition

nvim-lspconfig is great, but it doesn’t support all language servers that exist. You may want to set up a custom server where you manually define the cmd and the root_dir. This can also be done completely through servers and config tables similar to configuring servers that are supported by nvim-lspconfig! For these custom servers, the minimum requirement is defining a cmd in the config entry, but to get automatic starting of language servers you also need to set filetypes and root_dir. Here is a simple example setting up a Prolog LSP with swipl:

lua/plugins/astrolsp.lua
return {
  "AstroNvim/astrolsp",
  -- we need to use the function notation to get access to the `lspconfig` module
  ---@param opts AstroLSPOpts
  opts = function(plugin, opts)
    -- insert "prolog_lsp" into our list of servers
    opts.servers = opts.servers or {}
    table.insert(opts.servers, "prolog_lsp")


    -- extend our configuration table to have our new prolog server
    opts.config = require("astrocore").extend_tbl(opts.config or {}, {
      -- this must be a function to get access to the `lspconfig` module
      prolog_lsp = {
        -- the command for starting the server
        cmd = {
          "swipl",
          "-g",
          "use_module(library(lsp_server)).",
          "-g",
          "lsp_server:main",
          "-t",
          "halt",
          "--",
          "stdio",
        },
        -- the filetypes to attach the server to
        filetypes = { "prolog" },
        -- root directory detection for detecting the project root
        root_dir = require("lspconfig.util").root_pattern("pack.pl"),
      },
    })
  end,
}

LSP Setup Without Installer

AstroNvim comes with mason-lspconfig as an easy interface for setting up and installing language servers, but this might not be adequate for all users. The LSP installer doesn’t support all of the language servers that Neovim’s LSP config supports and some users may already have the language servers installed on their machine and don’t want to reinstall it separately. In these cases we have added an easy interface for setting up these servers. The following plugin specification for AstroLSP simply sets up pyright language server for a user with pyright already available on their system:

lua/plugins/astrolsp.lua
return {
  "AstroNvim/astrolsp",
  -- we must use the function override because table merging
  -- does not play nicely with list-like tables
  ---@param opts AstroLSPOpts
  opts = function(plugin, opts)
    -- safely extend the servers list
    opts.servers = opts.servers or {}
    vim.list_extend(opts.servers, {
      "pyright",
      -- add more servers as needed...
    })
  end,
}

Customizing auto-format on save

AstroNvim has made formatting on save part of the default functionality out of the box. If you don’t want your code to get auto formatted on save, you can disable it in the AstroLSP configuration:

lua/plugins/astrolsp.lua
return {
  "AstroNvim/astrolsp",
  ---@type AstroLSPOpts
  opts = {
    formatting = {
      format_on_save = false, -- enable or disable automatic formatting on save
    },
  },
}

We have also added an extension to just true or false for this option to give more the user the ability to disable the auto formatting for specific filetypes. For example:

lua/plugins/astrolsp.lua
return {
  "AstroNvim/astrolsp",
  ---@type AstroLSPOpts
  opts = {
    formatting = {
      format_on_save = {
        enabled = true, -- enable or disable
        ignore_filetypes = { -- disable format on save for specified filetypes
          "markdown",
          "python",
        },
      },
    },
  },
}

If you would rather use a whitelist of filetypes for formatting on save rather than a blacklist type model, you can do that as well with the allow_filetypes table. If you have allow_filetypes it will take precedence over ignore_filetypes. So please only use one of these options at a time. Here is an example:

lua/plugins/astrolsp.lua
return {
  "AstroNvim/astrolsp",
  ---@type AstroLSPOpts
  opts = {
    formatting = {
      format_on_save = {
        enabled = true, -- enable or disable
        allow_filetypes = { -- only allow formatting on save for these filetypes
          "lua",
          "python",
        },
      },
    },
  },
}

For even more control, you can provide a filter function with the key filter. This function takes a single parameter of the current buffer number and returns a boolean value of whether you want to format on save or not (true means format, false means do not format). This function will run on each save to calculate if it should format.

lua/plugins/astrolsp.lua
return {
  "AstroNvim/astrolsp",
  ---@type AstroLSPOpts
  opts = {
    formatting = {
      enabled = true, -- enable format on save
      filter = function(bufnr)
        -- any lua logic...
        return true -- return boolean whether or not to format
      end,
    },
  },
}

With the formatting on save enabled, we have also provided the mapping <Leader>uf and <Leader>uF to toggle the auto formatting temporarily for either the current buffer or globally (Note: Format on save must be enabled in the AstroLSP formatting options for this option and keybinding to do anything).

Controlling Formatting

Since Neovim v0.8 there have been improvements to how language servers are used for formatting files. Previously Neovim could only use a single language server to format files at a time and would prompt on each format if multiple were available. This led to users disabling formatting capabilities for different language servers and losing that functionality all together for convenience. Now you are able to format with many formatters at the same time and filter them with a function. To empower this, AstroNvim has a configuration option for controlling what formatters are used. This can be done either with a filter function or a list of disabled clients.

Disabling formatting for a filter function

Using the filter option you can supply filter function to be run on each client that has formatting capabilities and if it returns true then it will be used for formatting and if it returns false then it will not be used. This applies to whenever you format your code either on save, with <Leader>lf, or with :Format.

lua/plugins/astrolsp.lua
return {
  "AstroNvim/astrolsp",
  ---@type AstroLSPOpts
  opts = {
    formatting = {
      filter = function(client)
        -- disable formatting for lua_ls
        if client.name == "lua_ls" then
          return false
        end


        -- only enable null-ls for javascript files
        if vim.bo.filetype == "javascript" then
          return client.name == "null-ls"
        end


        -- enable all other clients
        return true
      end,
    },
  },
}

Disabling formatting for a list of language servers

Using the disabled option you can supply an array like list of language server client names and those clients will be disabled with you format your code either on save, with <Leader>lf, or with :Format.

lua/plugins/astrolsp.lua
return {
  "AstroNvim/astrolsp",
  ---@type AstroLSPOpts
  opts = {
    formatting = {
      disabled = {
        "lua_ls",
        "rust_analyzer",
      },
    },
  },
}

Using both filter function and disabled list

When using the options together, a client listed in the disabled list will always be disabled and then all other clients will then be passed into the filter function. For example, we can simplify our previous filter function by just disabling the lua_ls client in the disabled table:

lua/plugins/astrolsp.lua
return {
  "AstroNvim/astrolsp",
  ---@type AstroLSPOpts
  opts = {
    formatting = {
      disabled = { "lua_ls" },
      filter = function(client)
        -- only enable null-ls for javascript files
        if vim.bo.filetype == "javascript" then
          return client.name == "null-ls"
        end


        -- enable all other clients
        return true
      end,
    },
  },
}

Configure other formatting options

The formatting options also allows you to specify other parameters for the vim.lsp.buf.format() call. Any of the other formatting options are allowed to be used here to be used as the default options. This means being able to easily adjust the default timeout_ms for formatting in AstroNvim or making asynchronous formatting the default. For example you can do the following to increase the formatting timeout along with adjust the filtering:

lua/plugins/astrolsp.lua
return {
  "AstroNvim/astrolsp",
  ---@type AstroLSPOpts
  opts = {
    formatting = {
      format_on_save = true, -- enable or disable automatic formatting on save
      timeout_ms = 3200, -- adjust the timeout_ms variable for formatting
      disabled = { "lua_ls" },
      filter = function(client)
        -- only enable null-ls for javascript files
        if vim.bo.filetype == "javascript" then
          return client.name == "null-ls"
        end


        -- enable all other clients
        return true
      end,
    },
  },
}

LSP File Operations

AstroLSP provides a complete implementation of the file manipulation features provided by the LSP Specification through the astrolsp.file_operations module. These operations are useful when language servers provide functionality such as automatically updating import statements when files are renamed. Currently this includes:

  • workspace/willCreateFiles
  • workspace/didCreateFiles
  • workspace/willRenameFiles
  • workspace/didRenameFiles
  • workspace/willDeleteFiles
  • workspace/didDeleteFiles

This functionality was introduced in AstroNvim v4 disabled by default and will be enabled by default starting in AstroNvim v5. The module is used to integrate with the Neo-tree file explorer out of the box as well as the file renaming capability provided by AstroCore (require("astrocore").rename_file() which is bound to <Leader>R).

To enable the file operations in AstroNvim v4, you can configure them through the AstroLSP plugin opts:

lua/plugins/astrolsp.lua
return {
  "AstroNvim/astrolsp",
  ---@type AstroLSPOpts
  opts = {
    file_operations = {
      timeout = 10000, -- default timeout in ms for completing LSP operations
      operations = { -- enable all of the file operations
        willCreate = true,
        didCreate = true,
        willRename = true,
        didRename = true,
        willDelete = true,
        didDelete = true,
      },
    },
  },
}

The astrolsp.file_operations module is meant to provide a simple Lua API to allow easy integration with any file management plugins/workflows that users may have. Some example integration code can be found in the AstroLSP Documentation. Many of the AstroCommunity plugins such as mini.files already provide the necessary integration to execute the LSP file operations when appropriate.

LSP Specific Plugins

There are some plugins available for doing advanced setup of language servers that require the user to not use the lspconfig setup call and instead use their own plugin setup for handling this. AstroNvim provides a nice way to do this while still using mason-lspconfig for installing the language servers. You can use the setup_handlers table for specifying how language servers should be setup such as using a language specific plugin. This function for each handler has two parameters, the first is the name of the server and the second is the options we would be passing to the lspconfig setup call. These options include things such as our built in capabilities, on_attach, as well as the user defined options in the config table. Here are a couple examples for some common LSP plugins:

Typescript (typescript.nvim)

lua/plugins/typescript.lua
return {
  { "jose-elias-alvarez/typescript.nvim", lazy = true }, -- add lsp plugin
  {
    "AstroNvim/astrolsp",
    ---@type AstroLSPOpts
    opts = {
      setup_handlers = {
        -- add custom handler
        tsserver = function(_, opts)
          require("typescript").setup({ server = opts })
        end,
      },
    },
  },
  {
    "williamboman/mason-lspconfig.nvim",
    opts = {
      ensure_installed = { "tsserver" }, -- automatically install lsp
    },
  },
}

Deno (deno-nvim)

lua/plugins/deno.lua
return {
  { "sigmasd/deno-nvim", lazy = true }, -- add lsp plugin
  {
    "AstroNvim/astrolsp",
    ---@type AstroLSPOpts
    opts = {
      setup_handlers = {
        -- add custom handler
        denols = function(_, opts)
          require("deno-nvim").setup({ server = opts })
        end,
      },
    },
  },
  {
    "williamboman/mason-lspconfig.nvim",
    opts = {
      ensure_installed = { "denols" }, -- automatically install lsp
    },
  },
}

tsserver + denols

Since both tsserver and denols (and others such as eslint and prettier) attach to TypeScript/JavaScript files, some extra configuration may be required if both are installed.

To conditionally enable tsserver/denols based on the presence of package.json/deno.json, add the following plugin specs:

lua/plugins/typescript_deno.lua
return {
  "AstroNvim/astrolsp",
  ---@param opts AstroLSPOpts
  opts = function(plugin, opts)
    require("astrocore").extend_tbl(opts, {
      config = {
        denols = {
          root_dir = require("lspconfig.util").root_pattern(
            "deno.json",
            "deno.jsonc"
          ),
        },
        tsserver = {
          root_dir = require("lspconfig.util").root_pattern("package.json"),
        },
        -- eslint = {
        --   root_dir = require("lspconfig.util").root_pattern("package.json", ".eslintrc.json", ".eslintrc.js"),
        -- },
      },
    })
  end,
}

For none-ls packages (such as prettier, prettierd, or eslint_d), set the following to handlers in the mason-null-ls options:

lua/plugins/typescript_deno_null_ls.lua
return {
  "jay-babu/mason-null-ls.nvim",
  opts = {
    handlers = {
      -- for prettier
      prettier = function()
        require("null-ls").register(
          require("null-ls").builtins.formatting.prettier.with({
            condition = function(utils)
              return utils.root_has_file("package.json")
                or utils.root_has_file(".prettierrc")
                or utils.root_has_file(".prettierrc.json")
                or utils.root_has_file(".prettierrc.js")
            end,
          })
        )
      end,
      -- for prettierd
      prettierd = function()
        require("null-ls").register(
          require("null-ls").builtins.formatting.prettierd.with({
            condition = function(utils)
              return utils.root_has_file("package.json")
                or utils.root_has_file(".prettierrc")
                or utils.root_has_file(".prettierrc.json")
                or utils.root_has_file(".prettierrc.js")
            end,
          })
        )
      end,
      -- For eslint_d:
      eslint_d = function()
        require("null-ls").register(
          require("null-ls").builtins.diagnostics.eslint_d.with({
            condition = function(utils)
              return utils.root_has_file("package.json")
                or utils.root_has_file(".eslintrc.json")
                or utils.root_has_file(".eslintrc.js")
            end,
          })
        )
      end,
    },
  },
}

C/C++ (clangd_extensions.nvim)

lua/plugins/clangd.lua
return {
  {
    "AstroNvim/astrolsp",
    ---@type AstroLSPOpts
    opts = {
      config = {
        clangd = {
          capabilities = {
            offsetEncoding = "utf-8",
          },
        },
      },
    },
  },
  {
    "p00f/clangd_extensions.nvim", -- install lsp plugin
    lazy = true,
    init = function()
      -- load clangd extensions when clangd attaches
      local augroup =
        vim.api.nvim_create_augroup("clangd_extensions", { clear = true })
      vim.api.nvim_create_autocmd("LspAttach", {
        group = augroup,
        desc = "Load clangd_extensions with clangd",
        callback = function(args)
          if
            assert(vim.lsp.get_client_by_id(args.data.client_id)).name
            == "clangd"
          then
            require("clangd_extensions")
            -- add more `clangd` setup here as needed such as loading autocmds
            vim.api.nvim_del_augroup_by_id(augroup) -- delete auto command since it only needs to happen once
          end
        end,
      })
    end,
  },
  {
    "williamboman/mason-lspconfig.nvim",
    opts = {
      ensure_installed = { "clangd" }, -- automatically install lsp
    },
  },
}

Dart Flutter (flutter-tools.nvim)

Requires dart to be available on the system.

lua/plugins/flutter-tools.lua
return {
  { "akinsho/flutter-tools.nvim", lazy = true }, -- add lsp plugin
  {
    "AstroNvim/astrolsp",
    ---@param opts AstroLSPOpts
    opts = function(plugin, opts)
      opts.servers = opts.servers or {}
      table.insert(opts.servers, "dartls")


      opts = require("astrocore").extend_tbl(opts, {
        setup_handlers = {
          -- add custom handler
          dartls = function(_, dartls_opts)
            require("flutter-tools").setup({ lsp = dartls_opts })
          end,
        },
        config = {
          dartls = {
            -- any changes you want to make to the LSP setup, for example
            color = {
              enabled = true,
            },
            settings = {
              showTodos = true,
              completeFunctionCalls = true,
            },
          },
        },
      })
    end,
  },
}

Rust (rustaceanvim)

lua/plugins/rustaceanvim.lua
return {
  {
    'mrcjkb/rustaceanvim', -- add lsp plugin
    version = '^5',
    lazy = false, -- This plugin is already lazy
    opts = function(_, opts)
      local astrolsp_avail, astrolsp = pcall(require, "astrolsp")
      local astrolsp_opts = (astrolsp_avail and astrolsp.lsp_opts "rust_analyzer") or {}
      local server = {
        ---@type table | (fun(project_root:string|nil, default_settings: table|nil):table) -- The rust-analyzer settings or a function that creates them.
        settings = function(project_root, default_settings)
          local astrolsp_settings = astrolsp_opts.settings or {}


          local merge_table = require("astrocore").extend_tbl(default_settings or {}, astrolsp_settings)
          local ra = require "rustaceanvim.config.server"
          -- load_rust_analyzer_settings merges any found settings with the passed in default settings table and then returns that table
          return ra.load_rust_analyzer_settings(project_root, {
            settings_file_pattern = "rust-analyzer.json",
            default_settings = merge_table,
          })
        end,
      }
      return { server = require("astrocore").extend_tbl(astrolsp_opts, server) }
    end,
    -- configure `rustaceanvim` by setting the `vim.g.rustaceanvim` variable
    config = function(_, opts) vim.g.rustaceanvim = require("astrocore").extend_tbl(opts, vim.g.rustaceanvim) end,


  },
  {
    "AstroNvim/astrolsp",
    ---@type AstroLSPOpts
    opts = {
      handlers = { rust_analyzer = false }, -- Let rustaceanvim setup `rust_analyzer`
    },
  },
  {
    "williamboman/mason-lspconfig.nvim",
    opts = {
      ensure_installed = { "rust_analyzer" }, -- automatically install lsp
    },
  },
}

Java (nvim-jdtls)

lua/plugins/jdtls.lua
return {
  { "mfussenegger/nvim-jdtls", lazy = true }, -- load jdtls on module
  {
    "AstroNvim/astrolsp",
    ---@type AstroLSPOpts
    opts = {
      setup_handlers = {
        -- add custom handler
        jdtls = function(_, opts)
          vim.api.nvim_create_autocmd("Filetype", {
            pattern = "java", -- autocmd to start jdtls
            callback = function()
              if opts.root_dir and opts.root_dir ~= "" then
                require("jdtls").start_or_attach(opts)
              end
            end,
          })
        end,
      },
      config = {
        -- set jdtls server settings
        jdtls = function()
          -- use this function notation to build some variables
          local root_markers =
            { ".git", "mvnw", "gradlew", "pom.xml", "build.gradle" }
          local root_dir = require("jdtls.setup").find_root(root_markers)


          -- calculate workspace dir
          local project_name = vim.fn.fnamemodify(vim.fn.getcwd(), ":p:h:t")
          local workspace_dir = vim.fn.stdpath("data")
            .. "/site/java/workspace-root/"
            .. project_name
          os.execute("mkdir " .. workspace_dir)


          -- get the mason jdtls path
          local jdtls_files = vim.fn.expand("$MASON/share/jdtls")


          -- return the server config
          return {
            cmd = {
              "java",
              "-Declipse.application=org.eclipse.jdt.ls.core.id1",
              "-Dosgi.bundles.defaultStartLevel=4",
              "-Declipse.product=org.eclipse.jdt.ls.core.product",
              "-Dlog.protocol=true",
              "-Dlog.level=ALL",
              "-javaagent:" .. jdtls_files .. "/lombok.jar",
              "-Xms1g",
              "--add-modules=ALL-SYSTEM",
              "--add-opens",
              "java.base/java.util=ALL-UNNAMED",
              "--add-opens",
              "java.base/java.lang=ALL-UNNAMED",
              "-jar",
              jdtls_files .. "/plugins/org.eclipse.equinox.launcher.jar",
              "-configuration",
              jdtls_files .. "/config",
              "-data",
              workspace_dir,
            },
            root_dir = root_dir,
          }
        end,
      },
    },
  },
  {
    "williamboman/mason-lspconfig.nvim",
    opts = {
      ensure_installed = { "jdtls" },
    },
  },
}

Automatic Signature Help

Some users may want to have automatic pop ups of function signatures while editing with a language server similar to that of functionality provided by noice.nvim and lsp_signature.nvim. By default this behavior is disabled, but can easily be enabled by modifying features.signature_help in the AstroLSP opts:

lua/plugins/signature_help.lua
return {
  "AstroNvim/astrolsp",
  ---@type AstroLSPOpts
  opts = {
    features = {
      signature_help = true, -- enable automatic signature help popup globally on startup
    },
  },
}

Inlay Hints

Since Neovim v0.10 there is the ability to handle and render inline virtual text and therefore first class support of inlay hints. AstroLSP comes with a built in feature for enabling inlay hints easily as well as toggling them during runtime. By default inlay hints are disabled, but they can easily be enabled by default by modifying features.inlay_hints in the AstroLSP opts:

lua/plugins/inlay_hints.lua
return {
  "AstroNvim/astrolsp",
  ---@type AstroLSPOpts
  opts = {
    features = {
      inlay_hints = true, -- enable inlay hints globally on startup
    },
  },
}

Disable in Insert Mode

Some users may like the look of inlay hints but prefer for them to be disabled with actively editing text in insert mode. This recipe also respects the current state of inlay hints and will only toggle them if inlay hints are enabled in a given buffer. This can easily be achieved with the AstroLSP autocmds feature:

lua/plugins/no_insert_inlay_hints.lua
return {
  "AstroNvim/astrolsp",
  ---@type AstroLSPOpts
  opts = {
    autocmds = {
      no_insert_inlay_hints = {
        -- only create for language servers that support inlay hints
        -- (and only if vim.lsp.inlay_hint is available)
        cond = vim.lsp.inlay_hint and "textDocument/inlayHint" or false,
        {
          -- when going into insert mode
          event = "InsertEnter",
          desc = "disable inlay hints on insert",
          callback = function(args)
            local filter = { bufnr = args.buf }
            -- if the inlay hints are currently enabled
            if vim.lsp.inlay_hint.is_enabled(filter) then
              -- disable the inlay hints
              vim.lsp.inlay_hint.enable(false, filter)
              -- create a single use autocommand to turn the inlay hints back on
              -- when leaving insert mode
              vim.api.nvim_create_autocmd("InsertLeave", {
                buffer = args.buf,
                once = true,
                callback = function()
                  vim.lsp.inlay_hint.enable(true, filter)
                end,
              })
            end
          end,
        },
      },
    },
  },
}