LSP (Language Server Protocol)

For years, the biggest argument against terminal-based editors was that they couldn't match the intelligence of a full IDE. The Language Server Protocol changed that equation entirely. By connecting Neovim to the same language servers that power VS Code and other editors, you get go-to-definition, real-time diagnostics, refactoring, and more — without sacrificing the speed and flexibility you love about Vim. LSP is, without exaggeration, one of Neovim's killer features.

What you'll learn in this chapter:

• Understand what the Language Server Protocol is and how it connects Neovim to language servers

• Set up Mason, mason-lspconfig, and nvim-lspconfig for automatic server management

• Configure LSP keymaps for go-to-definition, hover, references, rename, and code actions

• Customize diagnostics display and set up format-on-save

• Add linting support beyond what LSP provides

What is LSP?

LSP is a protocol created by Microsoft that standardizes the communication between an editor and a language server. Instead of each editor implementing language support from scratch, they all talk to the same language servers.

┌──────────┐         ┌──────────────────┐
│  Neovim  │ ◄─LSP─► │  Language Server  │
│ (client) │         │  (pyright, gopls, │
│          │         │   tsserver, etc.) │
└──────────┘         └──────────────────┘

Key LSP Features

• Go to definition (gd) — jump to where a function/variable is defined

• Hover documentation (K) — show docs for the symbol under cursor

• Find references (gr) — see all usages of a symbol

• Rename (<leader>rn) — rename a symbol across the project

• Code actions (<leader>ca) — quick fixes, refactoring suggestions

• Diagnostics — inline errors and warnings

• Formatting — auto-format code on save

• Signature help — show function parameters as you type

Setting Up LSP

You need three components:

1. mason.nvim — installs language servers automatically

2. mason-lspconfig.nvim — bridges Mason and lspconfig

3. nvim-lspconfig — configures language servers

Plugin Spec

-- lua/plugins/lsp.lua
return {
    {
        'neovim/nvim-lspconfig',
        event = { 'BufReadPre', 'BufNewFile' },
        dependencies = {
            'williamboman/mason.nvim',
            'williamboman/mason-lspconfig.nvim',
        },
        config = function()
            -- Setup Mason first
            require('mason').setup()
            require('mason-lspconfig').setup({
                ensure_installed = {
                    'lua_ls',       -- Lua
                    'pyright',      -- Python
                    'ts_ls',        -- TypeScript/JavaScript
                    'gopls',        -- Go
                    'rust_analyzer', -- Rust
                },
                automatic_installation = true,
            })

            local lspconfig = require('lspconfig')
            local capabilities = vim.lsp.protocol.make_client_capabilities()

            -- If using nvim-cmp, enhance capabilities (see [Chapter 16: Autocompletion](16-autocompletion.md))
            local ok, cmp_lsp = pcall(require, 'cmp_nvim_lsp')
            if ok then
                capabilities = cmp_lsp.default_capabilities(capabilities)
            end

            -- Keymaps (only active when LSP is attached)
            vim.api.nvim_create_autocmd('LspAttach', {
                callback = function(event)
                    local map = function(keys, func, desc)
                        vim.keymap.set('n', keys, func, {
                            buffer = event.buf,
                            desc = 'LSP: ' .. desc,
                        })
                    end

                    map('gd', vim.lsp.buf.definition, 'Go to definition')
                    map('gD', vim.lsp.buf.declaration, 'Go to declaration')
                    map('gr', vim.lsp.buf.references, 'Find references')
                    map('gi', vim.lsp.buf.implementation, 'Go to implementation')
                    map('K', vim.lsp.buf.hover, 'Hover documentation')
                    map('<leader>rn', vim.lsp.buf.rename, 'Rename symbol')
                    map('<leader>ca', vim.lsp.buf.code_action, 'Code action')
                    map('<leader>D', vim.lsp.buf.type_definition, 'Type definition')
                    map('[d', vim.diagnostic.goto_prev, 'Previous diagnostic')
                    map(']d', vim.diagnostic.goto_next, 'Next diagnostic')
                    map('<leader>e', vim.diagnostic.open_float, 'Show diagnostic')
                    map('<leader>q', vim.diagnostic.setloclist, 'Diagnostics list')
                end,
            })

            -- Configure individual servers
            lspconfig.lua_ls.setup({
                capabilities = capabilities,
                settings = {
                    Lua = {
                        diagnostics = { globals = { 'vim' } },
                        workspace = { checkThirdParty = false },
                    },
                },
            })

            lspconfig.pyright.setup({ capabilities = capabilities })
            lspconfig.ts_ls.setup({ capabilities = capabilities })
            lspconfig.gopls.setup({ capabilities = capabilities })
            lspconfig.rust_analyzer.setup({ capabilities = capabilities })
        end,
    },
}

Diagnostics Configuration

Customize how diagnostics (errors, warnings) appear:

vim.diagnostic.config({
    virtual_text = {
        prefix = '●',
        source = 'if_many',
    },
    float = {
        source = 'if_many',
        border = 'rounded',
    },
    signs = true,
    underline = true,
    update_in_insert = false,
    severity_sort = true,
})

-- Custom diagnostic signs
local signs = { Error = ' ', Warn = ' ', Hint = '󰌵 ', Info = ' ' }
for type, icon in pairs(signs) do
    local hl = 'DiagnosticSign' .. type
    vim.fn.sign_define(hl, { text = icon, texthl = hl, numhl = '' })
end

Formatting

Format on Save

-- Simple format on save
vim.api.nvim_create_autocmd('BufWritePre', {
    callback = function()
        vim.lsp.buf.format({ async = false })
    end,
})

conform.nvim (Recommended)

For more control over formatting, use conform.nvim:

{
    'stevearc/conform.nvim',
    event = 'BufWritePre',
    opts = {
        formatters_by_ft = {
            lua = { 'stylua' },
            python = { 'black' },
            javascript = { 'prettier' },
            typescript = { 'prettier' },
            go = { 'gofmt' },
        },
        format_on_save = {
            timeout_ms = 500,
            lsp_fallback = true,
        },
    },
}

Linting

For linting beyond what LSP provides, use nvim-lint:

{
    'mfussenegger/nvim-lint',
    event = { 'BufReadPre', 'BufNewFile' },
    config = function()
        local lint = require('lint')
        lint.linters_by_ft = {
            python = { 'ruff' },
            javascript = { 'eslint' },
        }
        vim.api.nvim_create_autocmd({ 'BufWritePost', 'BufEnter' }, {
            callback = function()
                lint.try_lint()
            end,
        })
    end,
}

Common Language Servers

Language	Server	Install with Mason
Lua	lua_ls	:MasonInstall lua-language-server
Python	pyright or basedpyright	:MasonInstall pyright
TypeScript	ts_ls	:MasonInstall typescript-language-server
Go	gopls	:MasonInstall gopls
Rust	rust_analyzer	:MasonInstall rust-analyzer
C/C++	clangd	:MasonInstall clangd
Java	jdtls	:MasonInstall jdtls
HTML/CSS	html, cssls	:MasonInstall html-lsp css-lsp
JSON	jsonls	:MasonInstall json-lsp
YAML	yamlls	:MasonInstall yaml-language-server
Bash	bashls	:MasonInstall bash-language-server

Tip: Run :Mason to open the Mason UI and browse/install available servers.

Note: LSP provides language intelligence, while Treesitter (see Chapter 14: Treesitter) provides syntax-aware highlighting and text objects. They complement each other and are best used together.

Summary

The Language Server Protocol gives Neovim the same code intelligence features found in full IDEs -- go-to-definition, hover documentation, find references, rename, and real-time diagnostics -- all powered by external language servers. With Mason handling server installation and lspconfig handling configuration, setting up LSP is straightforward and reproducible across machines.

Key takeaways:

• LSP is a protocol, not a plugin. Neovim acts as the client; language servers (pyright, gopls, lua_ls, etc.) do the heavy lifting.

• Mason + mason-lspconfig + nvim-lspconfig is the standard three-part setup for managing and configuring language servers.

• LSP keymaps should be attached via the LspAttach autocmd so they only activate in buffers with an active language server.

• Diagnostics, formatting (with conform.nvim), and linting (with nvim-lint) can all be customized to fit your workflow.

Exercises

1. Install a language server with Mason -- Open Neovim and run :Mason to browse available servers. Install the language server for a language you use (e.g., lua-language-server for Lua). Verify it appears in :Mason as installed.

2. Verify LSP is working -- Open a source file in a language you have configured (e.g., a .lua or .py file). Use gd to go to a function definition, K to view hover documentation, and gr to find references.

3. Customize diagnostic display -- Configure diagnostics to use rounded borders on floating windows, show the ● prefix for virtual text, and sort by severity. Verify the changes by introducing a deliberate error in a source file.

4. Set up format on save -- Configure conform.nvim to automatically format your code on save. Add formatters for at least two languages you work with.

5. Add a new language server -- Pick a language not yet in your configuration (e.g., Go, Rust, or TypeScript). Install its server with Mason, add it to your ensure_installed list, and call lspconfig.<server>.setup(). Verify with :LspInfo.