Let's talk about v3.x

[VonHeikemen]

The branch for v3.x has been created. I'm thinking on making v3.x the default branch on September 20, so there is plenty of time to discuss.

v3.x is the branch that will have all the breaking changes I didn't want to make in v2.x (the ones listed in the Future Changes/Deprecation notice section).

The "goal" for v3.x is to delete code and move away from the .setup() function that does too many things.

Biggest change here is that lsp-zero will not manage the setup for mason.nvim anymore. No more .ensure_installed() function either. The ecosystem around mason.nvim is growing, and having a hidden setup in lsp-zero feels wrong. A duplicate setup of mason.nvim doesn't do any harm right now (I think), but that can change at any moment.

Moving on to the configuration. This is the equivalent of the old recommended config.

local lsp_zero = require('lsp-zero')

lsp_zero.on_attach(function(client, bufnr)
  lsp_zero.default_keymaps({buffer = bufnr})
end)

require('mason').setup({})
require('mason-lspconfig').setup({
  ensure_installed = {'tsserver', 'rust_analyzer'},
  handlers = {
    lsp_zero.default_setup,
    lua_ls = function()
      local lua_opts = lsp_zero.nvim_lua_ls()
      require('lspconfig').lua_ls.setup(lua_opts)
    end,
  },
})

If people don't install mason.nvim they can just list the servers using .setup_servers().

local lsp_zero = require('lsp-zero')

lsp_zero.on_attach(function(client, bufnr)
  lsp_zero.default_keymaps({buffer = bufnr})
end)

lsp_zero.setup_servers({'tsserver', 'rust_analyzer'})

The setup with mason.nvim looks kind of scary, but hopefully people won't care. They will get the same features, and the snippet is still copy/paste friendly (it will work without modifications). I made a guide that explains how to use mason.nvim with lsp-zero, hopefully that covers all the details people should know.

If the user doesn't configure nvim-cmp, lsp-zero will provide the essential configuration for it to work.

Moving from v2.x should not be painful. People who use the .ensure_installed() function will get this warning message.

[lsp-zero] The function .ensure_installed() has been removed.
Use the module mason-lspconfig to install your LSP servers.
See :help lsp-zero-guide:integrate-with-mason-nvim

The help page will have the same info as the guide on how to use mason.nvim with lsp-zero. I'm actually thinking of adding a link too, I know people new to Neovim don't know how to use the help page.

And there are migration guides:
migrate from v1.x to v3.x
migrate from v2.x to v3.x

If you have any feedback about this new version, now is the time to say something.

[Jendker]

The transition was easy for me. I think it's only important to communicate that manage_nvim_cmp arguments have to be moved to lsp.extend_cmp.

BTW. Do we need any of:

-- (Optional) Configure lua language server for neovim
require('lspconfig').lua_ls.setup(lsp.nvim_lua_ls())

lsp.setup()

Mentioned in the recommended setup from v2.x:

local lsp = require('lsp-zero').preset({})

lsp.on_attach(function(client, bufnr)
  lsp.default_keymaps({buffer = bufnr})
end)

-- (Optional) Configure lua language server for neovim
require('lspconfig').lua_ls.setup(lsp.nvim_lua_ls())

lsp.setup()

[VonHeikemen]

.setup() doesn't do anything. I wanted to avoid fatal errors for the people migrating, so .setup() is an empty function.

To configure the lua language server, I'm thinking telling people to copy a project specific .luarc.json into their Neovim config folder. Adding this next to your init.lua has the same effect as the lua_ls.setup() with the lsp-zero config.

{
  "runtime.version": "LuaJIT",
  "runtime.path": [
    "lua/?.lua",
    "lua/?/init.lua"
  ],
  "diagnostics.globals": ["vim"],
  "workspace.checkThirdParty": false,
  "workspace.library": [
    "/usr/share/nvim/runtime/lua",
    "/home/dev/.config/nvim/lua"
  ]
}

It would even help neovim detect the root folder of your Neovim config. Users will need to change the paths in workspace.library though.

[Jendker]

Hmm do these workspace.library paths need to be absolute? That would likely influence config portability.

[VonHeikemen]

Looks like relative path do work. Adding ./lua instead of the absolute path to the config folder seems to work.

[VonHeikemen]

When you want to configure a language using mason-lspconfig people have two choices:

• Add a custom handler:

require('mason-lspconfig').setup({
  ensure_installed = {'tsserver', 'rust_analyzer'},
  handlers = {
    lsp.default_setup,
    lua_ls = function()
      require('lspconfig').lua_ls.setup(lsp.nvim_lua_ls())
    end,
  },
})

• Exclude the server from the automatic setup and then configure it after mason-lspconfig

require('mason-lspconfig').setup({
  ensure_installed = {'tsserver', 'rust_analyzer'},
  handlers = {
    lsp.default_setup,
    lua_ls = lsp.noop,
  },
})

require('lspconfig').lua_ls.setup(lsp.nvim_lua_ls())

I like that the first option enforces the order of functions. Also, you won't get an error if the server is not installed. But I don't like the extra nesting.

The second options looks better, but then people would have to know the order in which to call each function.

I would like to know which one is "new user friendly".

[Jendker]

I vote for the first one as more "new user friendly".

[VonHeikemen]

This is what primeagen's config would look like using v3.x.

local lsp_zero = require('lsp-zero')

lsp_zero.on_attach(function(client, bufnr)
  local opts = {buffer = bufnr, remap = false}

  vim.keymap.set("n", "gd", function() vim.lsp.buf.definition() end, opts)
  vim.keymap.set("n", "K", function() vim.lsp.buf.hover() end, opts)
  vim.keymap.set("n", "<leader>vws", function() vim.lsp.buf.workspace_symbol() end, opts)
  vim.keymap.set("n", "<leader>vd", function() vim.diagnostic.open_float() end, opts)
  vim.keymap.set("n", "[d", function() vim.diagnostic.goto_next() end, opts)
  vim.keymap.set("n", "]d", function() vim.diagnostic.goto_prev() end, opts)
  vim.keymap.set("n", "<leader>vca", function() vim.lsp.buf.code_action() end, opts)
  vim.keymap.set("n", "<leader>vrr", function() vim.lsp.buf.references() end, opts)
  vim.keymap.set("n", "<leader>vrn", function() vim.lsp.buf.rename() end, opts)
  vim.keymap.set("i", "<C-h>", function() vim.lsp.buf.signature_help() end, opts)
end)

require('mason').setup({})
require('mason-lspconfig').setup({
  ensure_installed = {'tsserver', 'rust_analyzer'},
  handlers = {
    lsp_zero.default_setup,
    lua_ls = function()
      local lua_opts = lsp_zero.nvim_lua_ls()
      require('lspconfig').lua_ls.setup(lua_opts)
    end,
  }
})

local cmp = require('cmp')

cmp.setup({
  sources = {
    {name = 'path'},
    {name = 'nvim_lsp'},
    {name = 'nvim_lua'},
  },
  mapping = cmp.mapping.preset.insert({
    ['<C-Space>'] = cmp.mapping.complete(),
  }),
})

[guoliang]

do you need to explicit define keymaps for gd, K and so on. when I check in the helper lsp-zero-keybindings it seems like it should be there by default?

[VonHeikemen]

ThePrimeagen doesn't use lsp-zero's keybindings.

lsp-zero's keybindings are opt-in, they are only active if you have this in your config.

lsp.on_attach(function(client, bufnr)
  lsp.default_keymaps({buffer = bufnr})
end)

[fmbarina]

Just made the transition from v1 to dev-v3, and it went well (mind you, I'm not good at this).

Though a little lost at first, the documentation helped a lot and now not only do I think my lsp setup is way more organized, I also feel that I understand how it works a lot better. I'm very grateful for all the guidance.

• For what it's worth, definitely agree with moving the mason setup out of lsp-zero.
• Seriously, love the docs, specially when it comes to explaining the inner workings and how to integrate other plugins.

[simonmandlik]

Thank you very much!

[simonmandlik]

@VonHeikemen just my 2 cents here, I have just spent a fair amount of time debugging why my clangd LSP is sometimes behaving funky. It seemed random at times, but eventually I discovered that it is due to cmp.setup() being called two times, once in lsp-zero.extend_cmp and once in my config when setting up keybindings.

If extend_cmp will be run automatically, I would really emphasize in docs that it also "setups" cmp, not only "extends" and what it implies.

Thanks!

[VonHeikemen]

@simonmandlik Can you tell me the specifics of the funky behavior in clangd?

I don't see how calling cmp.setup() will affect your LSP. I read nvim-cmp's source code, there is no reason why that should happen. nvim-cmp's setup function only modifies internal variables.

The automatic setup lsp-zero runs is sligthly different from extend_cmp(). When the automatic setup kicks in it only modifies sources if its empty, it only adds the mappings if mapping is empty, and the snippet expand function only works as a fallback. The whole thing acts as a backup.

In autocomplete.md I say lsp-zero is going to run some code for you, and I show the snippet. It is also mentioned that if the user wants to add a new source they should also add the source for the LSP, so they do not lose the LSP completions. I do the same thing for the mappings.

[simonmandlik]

It is very hard to track down what exactly is going wrong, so first off sorry for being quite vague..

The issue is described here (at first I thought it is a problem with nvim-cmp), there are videos in the comments. There is also an MWE init.lua, which quite consistently reproduces the issue for me (but not always).

I have noticed that the issue is more likely to occur than not if I add disables for <C-n> and <C-p> into nvim-cmp config. That's what lead me to believe that it is an issue in nvim-cmp. But then I tried setting up without lsp-zero and everything worked flawlessly. So my best (wild) guess is the double call of setup.

[VonHeikemen]

@simonmandlik I think I figure out the issue. Problem was how lazy.nvim was loading the plugins. When lsp-zero was loading first it didn't have a way to know if nvim-cmp was installed, as a consequence the option called capabilities was not setup correctly in lspconfig. When nvim-cmp loaded first, everything worked as expected.

I deleted the code that was causing the issue. Now instead of checking for nvim-cmp lsp-zero will look for the module cmp_nvim_lsp. If you set hrsh7th/cmp-nvim-lsp as a dependency of lsp-zero everything should work fine.

[mezdelex]

Another one who migrated without any issues to dev-v3 here.
Thanks!

[VonHeikemen]

Awesome. Is nice to hear that.

Remember that after september 20 you will have to change the name of the branch from dev-v3 to v3.x.

[mezdelex]

Will v3.x be the default branch or should be explicitly specified in the branch attribute?

[VonHeikemen]

@mezdelex you have to change the branch name manually in your plugin manager.

[VonHeikemen]

If anyone out there is using a debian based distro, which has Neovim v0.7 in the official repo, you can use the branch compat-07. That branch will have the same api as v3.x.

[simonmandlik]

@VonHeikemen, I'm trying to put together a minimal config including lazy.nvim, but I can't get it working. What's wrong with the following init.lua please?

local root = vim.fn.fnamemodify("./.repro", ":p")
for _, name in ipairs({ "config", "data", "state", "cache" }) do
    vim.env[("XDG_%s_HOME"):format(name:upper())] = root .. "/" .. name
end
local lazypath = root .. "/plugins/lazy.nvim"
if not vim.loop.fs_stat(lazypath) then
    vim.fn.system({ "git", "clone", "--filter=blob:none", "https://github.com/folke/lazy.nvim.git", lazypath, })
end
vim.opt.runtimepath:prepend(lazypath)

local plugins = {
        {
        "VonHeikemen/lsp-zero.nvim",
        branch = "dev-v3",
        dependencies = {
            "neovim/nvim-lspconfig",
            "williamboman/mason.nvim",
            "williamboman/mason-lspconfig.nvim",
        },

        config = function()
            local lsp = require("lsp-zero")

            lsp.on_attach(function(client, bufnr)
              lsp.default_keymaps({buffer = bufnr})
            end)

            require("mason").setup {}
            require("mason-lspconfig").setup {
                ensure_installed = { "clangd" },
                handlers = { lsp.default_setup }
            }
        end
    },
}

require("lazy").setup(plugins, {
    root = root .. "/plugins",
})

[VonHeikemen]

vim.fn.fnamemodify("./.repro", ":p") will already include a slash at the end, so doing stuff like root .. "/" .. name will cause your path to have a double slash in there. Maybe that's the issue. But everything else looks good.

[simonmandlik]

That couldn't have been the case, because lazy worked fine, and judging from :LspInfo, clang was successfully installed, just not attached.

But it works now, I deleted all the folders and started from scratch, so I guess there were leftovers there that broke it

[VonHeikemen]

The v3.x branch has been created.

The default branch right now is still v2.x, so this is a good time to check your plugin manager and track the branch you wish to use.