# Managing LSP Servers with Mason **Mason** is a package manager for Neovim that installs and manages LSP servers, DAP servers, linters, and formatters. It comes pre-configured with LazyVim and provides a simple UI for managing language tooling. ## What Mason Does Mason handles the complexity of LSP server installation: - **Automated installation:** Downloads and configures language servers - **Isolated environments:** Each server runs in its own environment (no conflicts) - **Cross-platform:** Works on macOS, Linux, and Windows - **No manual dependency management:** Handles Node.js, Python, Go, and other runtime requirements - **Version management:** Update or rollback servers easily - **Integration with LazyVim:** Installed servers are automatically detected and configured **The key benefit:** You never need to manually install LSP servers with npm/pip/cargo/etc. Mason does it all. ## Opening Mason Inside Neovim: ```vim :Mason ``` Or use the LazyVim keybinding: ``` <Space> + c + m ``` This opens the Mason UI showing all available and installed packages. ## Mason UI Navigation The Mason interface uses simple keybindings: | Key | Action | |-----|--------| | `i` | Install package under cursor | | `u` | Update package under cursor | | `U` | Update all installed packages | | `X` | Uninstall package under cursor | | `/` | Filter/search packages | | `g?` | Show help | | `q` | Quit Mason UI | | `j/k` | Navigate down/up | | `Ctrl+f/b` | Scroll down/up | ## Installing Language Servers ### Interactive Installation 1. Open Mason: `:Mason` 2. Navigate to the server you want (use `j/k` or `/` to search) 3. Press `i` to install 4. Wait for installation to complete (progress shows in UI) 5. Press `q` to close Mason **Example workflow:** ``` :Mason /typescript (search for typescript) i (install typescript-language-server) q (quit when done) ``` ### Command-Line Installation Install directly without opening the UI: ```vim :MasonInstall typescript-language-server :MasonInstall lua-language-server :MasonInstall pyright ``` Install multiple servers at once: ```vim :MasonInstall typescript-language-server html-lsp css-lsp json-lsp ``` ## Essential Language Servers Here are the most commonly needed LSP servers organized by use case: ### Web Development (JavaScript/TypeScript) ```vim :MasonInstall typescript-language-server :MasonInstall tailwindcss-language-server :MasonInstall eslint-lsp :MasonInstall prettier ``` **What they do:** - `typescript-language-server` - Autocomplete, type checking, refactoring for TS/JS - `tailwindcss-language-server` - Tailwind CSS class autocomplete and validation - `eslint-lsp` - Linting and code quality checks - `prettier` - Code formatting ### Web Fundamentals (HTML/CSS/JSON) ```vim :MasonInstall html-lsp :MasonInstall css-lsp :MasonInstall json-lsp ``` **What they do:** - `html-lsp` - HTML tag completion, validation - `css-lsp` - CSS property completion, validation - `json-lsp` - JSON validation, schema support ### Lua (Neovim Configuration) ```vim :MasonInstall lua-language-server :MasonInstall stylua ``` **What they do:** - `lua-language-server` - Autocomplete for Lua, Neovim API aware - `stylua` - Lua code formatter ### Python ```vim :MasonInstall pyright :MasonInstall ruff-lsp :MasonInstall black ``` **What they do:** - `pyright` - Type checking, autocomplete, refactoring - `ruff-lsp` - Fast Python linting - `black` - Python code formatter ### Rust ```vim :MasonInstall rust-analyzer ``` **What it does:** - `rust-analyzer` - Full Rust language support (autocomplete, diagnostics, macros) ### Markdown ```vim :MasonInstall marksman :MasonInstall markdown-toc ``` **What they do:** - `marksman` - Markdown link completion, navigation, diagnostics - `markdown-toc` - Generate table of contents ### Shell Scripts ```vim :MasonInstall bash-language-server :MasonInstall shellcheck :MasonInstall shfmt ``` **What they do:** - `bash-language-server` - Bash/zsh script completion and diagnostics - `shellcheck` - Shell script linting - `shfmt` - Shell script formatting ### Docker ```vim :MasonInstall dockerfile-language-server :MasonInstall docker-compose-language-service ``` **What they do:** - `dockerfile-language-server` - Dockerfile syntax and best practices - `docker-compose-language-service` - Docker Compose YAML validation ### YAML/TOML ```vim :MasonInstall yaml-language-server :MasonInstall taplo ``` **What they do:** - `yaml-language-server` - YAML validation with schema support - `taplo` - TOML language support and formatting ## Updating Language Servers ### Update All Servers ```vim :MasonUpdate ``` Or in the UI: ``` :Mason U (capital U - updates all installed packages) ``` ### Update Single Server In the Mason UI: ``` :Mason /typescript (navigate to server) u (lowercase u - update this package) ``` Or via command: ```vim :MasonUpdate typescript-language-server ``` ## Uninstalling Language Servers ### Via UI ``` :Mason /server-name (navigate to installed server) X (capital X - uninstall) ``` ### Via Command ```vim :MasonUninstall typescript-language-server ``` ## Checking Installation Status ### See All Installed Servers ```vim :Mason ``` Installed servers show a **green checkmark** (✓) in the UI. ### Check Specific Server Status ```vim :MasonInstall typescript-language-server ``` If already installed, you'll see: `"typescript-language-server" is already installed` ### Verify LSP is Running Check if an LSP server is active for the current file: ```vim :LspInfo ``` This shows: - Which LSP servers are attached to the current buffer - Server status (running, stopped, etc.) - Server capabilities (formatting, hover, etc.) - Log file location for debugging ## Troubleshooting ### Server Won't Install **Problem:** Installation fails with errors. **Solution:** 1. **Check the Mason log:** ```vim :MasonLog ``` 2. **Common issues:** - Missing dependencies (Mason usually handles this, but some servers need system packages) - Network issues (firewall blocking downloads) - Insufficient disk space 3. **Retry installation:** ```vim :MasonUninstall server-name :MasonInstall server-name ``` ### LSP Server Not Working After Installation **Problem:** Server installed but not providing completions/diagnostics. **Solution:** 1. **Check if server is running:** ```vim :LspInfo ``` 2. **Restart LSP:** ```vim :LspRestart ``` 3. **Check file type:** Some servers only activate for specific file types. Verify with: ```vim :set filetype? ``` 4. **Check LazyVim LSP config:** Make sure the server is configured in LazyVim (usually automatic, but custom setups may need config) ### Server Installed But Not in PATH **Problem:** Server installed via Mason but not available in terminal. **This is normal!** Mason installs servers in Neovim's data directory, not system-wide: ``` ~/.local/share/nvim/mason/bin/ ``` **If you need system-wide access:** Add to your `~/.zshrc`: ```bash # Add Mason binaries to PATH export PATH="$HOME/.local/share/nvim/mason/bin:$PATH" ``` Then: ```bash source ~/.zshrc ``` **Note:** This is usually not needed - Mason servers are meant for Neovim use only. ### Wrong Server Version **Problem:** Need a specific version of a language server. **Solution:** Mason installs the latest stable version by default. To use a different version: 1. **Uninstall current version:** ```vim :MasonUninstall server-name ``` 2. **Install specific version:** Currently, Mason doesn't support version pinning directly. For specific versions, install manually: ```bash # Example: Install specific TypeScript version globally npm install -g [email protected] typescript-language-server ``` Then configure LazyVim to use the global installation (see Mason configuration below). ## Advanced Configuration ### Customizing Mason in LazyVim Create `~/.config/nvim/lua/plugins/mason.lua`: ```lua return { { "williamboman/mason.nvim", opts = { -- Use system PATH first (prefer globally installed servers) PATH = "prepend", -- UI settings ui = { border = "rounded", width = 0.8, height = 0.8, icons = { package_installed = "✓", package_pending = "➜", package_uninstalled = "✗", }, }, -- Install these servers automatically ensure_installed = { "typescript-language-server", "lua-language-server", "html-lsp", "css-lsp", "json-lsp", "marksman", }, }, }, } ``` **Key options explained:** - `PATH = "prepend"` - Use global installations (npm/brew/etc.) before Mason's - `ensure_installed` - Auto-install these servers when LazyVim starts - `ui.border` - Change border style of Mason window ### Auto-Install Servers on LazyVim Startup To automatically install specific servers when LazyVim starts: ```lua return { { "williamboman/mason.nvim", opts = { ensure_installed = { -- Web dev "typescript-language-server", "tailwindcss-language-server", "html-lsp", "css-lsp", -- Config files "lua-language-server", "json-lsp", "yaml-language-server", -- Formatters "prettier", "stylua", -- Linters "eslint-lsp", }, }, }, } ``` Now when you launch LazyVim on a new machine, these servers install automatically. ### Custom Server Configuration Some LSP servers need custom configuration. Create `~/.config/nvim/lua/plugins/lsp.lua`: ```lua return { { "neovim/nvim-lspconfig", opts = { servers = { -- TypeScript with custom settings tsserver = { settings = { typescript = { inlayHints = { includeInlayParameterNameHints = "all", includeInlayFunctionParameterTypeHints = true, }, }, }, }, -- Lua with Neovim API awareness lua_ls = { settings = { Lua = { workspace = { checkThirdParty = false, }, diagnostics = { globals = { "vim" }, }, }, }, }, }, }, }, } ``` ## Mason vs Manual Installation | Method | Pros | Cons | |--------|------|------| | **Mason** | Automatic, isolated, easy updates, works everywhere | Limited version control | | **Homebrew** | System-wide, version pinning | Manual PATH config, platform-specific | | **npm/pip/cargo** | Version control, familiar | Dependency conflicts, manual setup | | **Bun** | Fast, modern | Compatibility issues with some servers | **Recommendation:** Use Mason for everything unless you have a specific reason to install manually. ## Quick Reference Commands ### Installation ```vim :Mason " Open UI :MasonInstall server-name " Install server :MasonInstall server1 server2 server3 " Install multiple ``` ### Management ```vim :MasonUpdate " Update all servers :MasonUpdate server-name " Update specific server :MasonUninstall server-name " Remove server :MasonLog " View installation logs ``` ### LSP Status ```vim :LspInfo " Check running LSP servers :LspRestart " Restart LSP for current buffer :LspStop " Stop LSP for current buffer :LspStart " Start LSP for current buffer ``` ### Health Check ```vim :checkhealth mason " Check Mason installation :checkhealth lsp " Check LSP configuration ``` ## Common LSP Server Names Quick reference for Mason package names: | Language/Tool | Mason Package Name | |--------------|-------------------| | TypeScript/JavaScript | `typescript-language-server` | | Tailwind CSS | `tailwindcss-language-server` | | HTML | `html-lsp` | | CSS | `css-lsp` | | JSON | `json-lsp` | | Lua | `lua-language-server` | | Python | `pyright` or `pylsp` | | Rust | `rust-analyzer` | | Go | `gopls` | | Bash/Shell | `bash-language-server` | | Markdown | `marksman` | | Docker | `dockerfile-language-server` | | YAML | `yaml-language-server` | | Prettier (formatter) | `prettier` | | ESLint (linter) | `eslint-lsp` | **Search in Mason UI** if you're not sure of the exact name - the search is forgiving. ## Integration with LazyVim Workflows Mason is just one piece of the LazyVim ecosystem: 1. **Mason installs** the language servers 2. **nvim-lspconfig** configures them 3. **LazyVim** provides keybindings and UI 4. **nvim-cmp** provides completions using LSP data When you press: - `gd` - Go to definition (uses LSP server installed by Mason) - `K` - Hover docs (uses LSP server installed by Mason) - `<Space>ca` - Code actions (uses LSP server installed by Mason) **Everything just works** because Mason, lspconfig, and LazyVim are tightly integrated. ## Next Steps Once you've installed language servers with Mason: - **Learn LSP keybindings:** See [[Installing LazyVim]] for essential shortcuts - **Customize servers:** See [[LazyVim LSP Configuration]] for advanced setup - **Add formatters/linters:** Use Mason to install tools like Prettier, ESLint, Black - **Check server health:** Run `:checkhealth lsp` to verify everything works ## Links ### Mason GitHub Repository - **URL:** https://github.com/williamboman/mason.nvim - **Summary:** Official Mason repository with documentation, issue tracker, and configuration examples for managing LSP servers in Neovim. - **Related:** [[Installing LazyVim]], [[LazyVim Setup]] ### Mason Registry - **URL:** https://mason-registry.dev/ - **Summary:** Browse all available packages in Mason's registry - LSP servers, formatters, linters, and DAP servers with installation names and descriptions. - **Related:** [[Installing LazyVim]] ### nvim-lspconfig Documentation - **URL:** https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md - **Summary:** Official documentation for configuring LSP servers in Neovim, including server-specific settings and requirements. - **Related:** [[Installing LazyVim]], [[LazyVim Setup]]