Learn Neovim - Built-in LSP (Language Server Protocol) & mason.nvim

#Introduction

After building grammar-based code understanding with nvim-treesitter in episode 14 — accurate syntax highlighting, code folding, and textobjects — in this episode we jump to a higher level: the editor's ability to truly understand the semantics of your code. We will connect Neovim to the Language Server Protocol (LSP) and manage all language servers with mason.nvim.

Why is this important in the real world? Imagine you are refactoring on a backend team: renaming the method getUserById to findUser. Without LSP, you would have to find all the call sites manually — risking missing a file, or — worse — missing one call site that introduces a runtime bug only discovered in production. With LSP, one semantics-aware rename command replaces all references across the entire project, including files that are not currently open. This is the main differentiator between a "text editor" and an "IDE", and now you can have it without leaving Neovim.

#Main Discussion

#Understanding the LSP Architecture: Client-Server

LSP solves a huge problem that has plagued the editor world for years: every language has its own tooling (compilers, linters, type checkers), and every editor must integrate with each tool individually. The result is massive duplication of effort.

LSP standardizes all of this with a client-server architecture:

┌─────────────────┐         ┌─────────────────┐
│  Neovim Client  │  JSON-RPC │  Language Server │
│  (nvim-lspconfig) ◄────────►  (tsserver, gopls, │
│  ─────────────── │  over    │   pyright, ...)  │
│  • gd, K, gr    │  stdio   │  • parse project  │
│  • diagnostics  │  WebSocket│  • type check    │
│  • completion   │          │  • indexing       │
└─────────────────┘          └─────────────────┘

An explanation of each component:

• Language Server — a separate process (which can even run on a different machine!) that understands one language in depth. It parses your project, does type checking, and builds a global symbol database. Examples: gopls for Go, tsserver for TypeScript, pyright for Python.
• Client (Neovim) — the program that presents results to you and sends requests. In Neovim, this is the built-in vim.lsp API + the nvim-lspconfig plugin that handles the wiring.
• Protocol (JSON-RPC) — the communication language. Both sides exchange structured messages like textDocument/definition (the client asks "where is the definition of this symbol?") and textDocument/publishDiagnostics (the server reports "there is an error on line 12").

The key concept: the server does not care which editor is used. The same server serves VS Code, Neovim, Emacs, and others. Once a language server is written, all editors can use it. This is why Microsoft — the creator of LSP in 2016 — called it "the protocol of the future": you no longer depend on a particular team to support your editor.

#The Role of Three Plugins in One Pipeline

LSP integration in modern Neovim is built from three plugin layers working in sequence:

Mason is not part of LSP itself — it is a package manager for editor tools: language servers, linters, and formatters. We will use it again in episode 17 for linters & formatters.

#Configuring mason.nvim with lazy.nvim

return {
  {
    "williamboman/mason.nvim",
    cmd = { "Mason", "MasonInstall", "MasonUninstall", "MasonUpdate" },
    config = function()
      require("mason").setup({
        ui = {
          border = "rounded",
          icons = {
            package_installed = "✓",
            package_pending = "➜",
            package_uninstalled = "✗",
          },
        },
      })
    end,
  },
}

Why cmd = { "Mason", ... }? This is command-based lazy-loading as discussed in episode 9 — the Mason plugin is only loaded when you actually open its UI (:Mason) or run its install commands. Since Mason is rarely used every minute, burdening startup time just for it makes no sense.

Now run :Mason inside Neovim. You will see an interactive UI displaying hundreds of packages. Use / to search, then press i to install the highlighted package, u to uninstall, and X to update. Think of it like a marketplace: all language servers, linters, and formatters in one place, installed to the ~/.local/share/nvim/mason directory automatically without the hassle of configuring PATH.

#Integrating mason-lspconfig & nvim-lspconfig

After Mason manages the binaries, we need to tell nvim-lspconfig which server to run and with what configuration. Here is the complete configuration:

return {
  {
    "williamboman/mason-lspconfig.nvim",
    dependencies = { "williamboman/mason.nvim" },
    opts = {
      ensure_installed = {
        "lua_ls",        -- Lua
        "tsserver",      -- TypeScript / JavaScript
        "pyright",       -- Python
        "gopls",         -- Go
        "bashls",        -- Bash / Shell
        "yamlls",        -- YAML
        "jsonls",        -- JSON
        "dockerls",      -- Dockerfile
      },
      automatic_enable = true,
    },
  },
 
  {
    "neovim/nvim-lspconfig",
    dependencies = {
      "williamboman/mason.nvim",
      "williamboman/mason-lspconfig.nvim",
    },
    config = function()
      local capabilities = vim.lsp.protocol.make_client_capabilities()
      -- Foundation untuk nvim-cmp di episode 16
      capabilities.textDocument.completion.completionItem.snippetSupport = true
 
      local lspconfig = require("lspconfig")
 
      local on_attach = function(_, bufnr)
        local opts = { buffer = bufnr, silent = true }
 
        vim.keymap.set("n", "gd", vim.lsp.buf.definition, opts)
        vim.keymap.set("n", "gr", vim.lsp.buf.references, opts)
        vim.keymap.set("n", "K", vim.lsp.buf.hover, opts)
        vim.keymap.set("n", "<leader>rn", vim.lsp.buf.rename, opts)
        vim.keymap.set("n", "<leader>ca", vim.lsp.buf.code_action, opts)
        vim.keymap.set("n", "<leader>e", vim.diagnostic.open_float, opts)
        vim.keymap.set("n", "[d", vim.diagnostic.goto_prev, opts)
        vim.keymap.set("n", "]d", vim.diagnostic.goto_next, opts)
      end
 
      require("mason-lspconfig").setup({
        handlers = {
          function(server)
            lspconfig[server].setup({
              capabilities = capabilities,
              on_attach = on_attach,
            })
          end,
        },
      })
    end,
  },
}

Let's dissect the important parts:

• mason-lspconfig.opts.ensure_installed — the list of servers automatically installed by Mason when the config first loads. Similar to ensure_installed in treesitter.
• automatic_enable = true — installed servers are automatically enabled for the appropriate filetypes.
• handlers — the function called for every detected server. This is the DRY pattern: a single setup() with the same capabilities and on_attach applies to all servers, without writing a block per server. If a server needs special configuration (e.g. lua_ls with settings), you can override it with a specifically-named handler.
• on_attach — the function called every time a server attaches to a buffer. This is where all LSP keymaps are defined, with buffer = bufnr so they only apply to the active buffer.

#LSP Keymaps: The Gateway to IDE Features

Now let's define the LSP keymaps that are standard in almost all modern Neovim distributions (LazyVim, NvChad, and others use the same pattern):

A quick real-world usage guide:

1. Hover the cursor over a function name, press gd — you immediately jump to its definition. Press Ctrl+o to return to your previous position (the jump list, episode 3).
2. Press K on a function — a documentation window appears with the signature and docstring, without opening a browser.
3. Press <leader>rn, type the new name, press Enter — all references across the project change, even in files not open. This is what makes refactoring in Neovim as comfortable as in a GUI IDE.
4. Press <leader>ca when there is a red line — a list of quick fixes appears like "import this symbol" or "auto-fix typo".

#The LSP Workflow in One Coding Session

Now let's string all the LSP keymaps into one realistic workflow — writing a new function in a TypeScript project:

1. Ketik nama fungsi baru → muncul warning "x is declared but never used" (diagnostic).
2. Tekan K pada sebuah tipe → dokumentasi & type signature muncul, tanpa buka browser.
3. Saat memanggil fungsi dari library → gd untuk lompat ke definisinya, Ctrl+o kembali.
4. Error muncul di baris 12 → ]d lompat ke sana, <leader>e lihat detail lengkap.
5. Ingin ubah nama variabel di seluruh project → <leader>rn, ketik baru, Enter.
6. Mau auto-import symbol → letakkan kursor pada nama, <leader>ca, pilih "Add import".

Notice the flow: writing, verifying, refactoring, and fixing all happen in one editor, without leaving the buffer and without switching context. This is what the editor understands code means — not merely coloring text.

#Per-Language Configuration: TypeScript, Python, Go

The following three servers are the most commonly used by production teams. Notice how each has specific requirements:

require("lspconfig").tsserver.setup({
  capabilities = capabilities,
  on_attach = on_attach,
  root_dir = require("lspconfig").util.root_pattern("package.json", "tsconfig.json", ".git"),
  single_file_support = false,
})

require("lspconfig").pyright.setup({
  capabilities = capabilities,
  on_attach = on_attach,
  settings = {
    python = {
      analysis = {
        autoSearchPaths = true,
        useLibraryCodeForTypes = true,
        typeCheckingMode = "basic",
      },
    },
  },
})

require("lspconfig").gopls.setup({
  capabilities = capabilities,
  on_attach = on_attach,
  settings = {
    gopls = {
      analyses = { unusedparams = true },
      staticcheck = true,
    },
  },
})

Key points per language:

• tsserver uses a root_dir based on package.json/tsconfig.json — the server only lives if the project has one of them. single_file_support = false prevents standalone .ts files (without a project) from triggering the server, because without a tsconfig type-checking would be half-hearted.
• pyright needs settings.python.analysis to control how aggressive its type checking is. basic is a good middle ground between accuracy and noise.
• gopls supports staticcheck — a static analysis engine that catches bugs the compiler does not detect. Always enable it for Go codebases.

#Common LSP & Mason Pitfalls

#Closing

In episode 15 we understood the LSP client-server architecture and why it has become the universal standard that solves editor tooling fragmentation. We built a complete pipeline: mason.nvim as the server package manager, mason-lspconfig.nvim as the bridge, and nvim-lspconfig as the configurator — plus the standard LSP keymaps (gd, gr, K, <leader>rn, <leader>ca, <leader>e) and specific configurations for TypeScript, Python, and Go.

You now have a Neovim that understands code semantically, on par with commercial IDEs, yet running in a terminal. But there is still one gap you can feel: while typing, there is no autocompletion popup showing suggestions from this language server.

In episode 16, we will fill that gap with the Autocompletion Engine using nvim-cmp & Snippets — a completion popup that merges LSP suggestions, buffer, path, and snippets into one agile interface. Stay motivated!