NEOVIM · MACOS · NOTES FROM A SETUP
A pro Neovim in an afternoon
How we swapped the Mac's stock Vim for Neovim with LazyVim: language servers, fuzzy finding, Treesitter, git, all installed ahead of time so the first launch is ready to work.
Why bother
macOS ships Vim at /usr/bin/vim. It's part of the system, protected by System Integrity Protection, so it can't be deleted, and a macOS update would put it back anyway. The practical move is to stop reaching for it: Neovim from Homebrew, and two lines in ~/.zshrc so muscle memory lands in the right place.
# ~/.zshrc
alias vi='nvim'
alias vim='nvim'
export EDITOR='nvim'Neovim on its own is a plain editor with a very good engine underneath: a built-in LSP client, Treesitter, and Lua for configuration. What makes it feel like a professional's editor is the layer on top, and that's where LazyVim comes in.
What sits on top of Neovim
LazyVim is a distribution: a curated, maintained set of plugins with sensible defaults, which you then override in your own files. It's what many long-time Vim users now start from instead of writing a thousand-line config by hand.
lazyvim.json: Python, TypeScript, JSON, Markdown, YAML, TOML, Docker.The install, step by step
Everything below ran once. The goal was a first launch with nothing left to download.
The tools LazyVim leans on. ripgrep for searching, fd for finding files, lazygit for git, and the tree-sitter CLI for compiling parsers. rg, fzf, Node and a Nerd Font (JetBrains Mono) were already on this Mac.
brew upgrade neovim brew install fd lazygit tree-sitter-cli
The starter config. Clone it and drop its git history, so the config is yours to commit wherever you like.
git clone --depth 1 https://github.com/LazyVim/starter ~/.config/nvim rm -rf ~/.config/nvim/.git
Pick the languages. Extras are listed in ~/.config/nvim/lazyvim.json. You can also toggle them later from :LazyExtras.
{
"extras": [
"lazyvim.plugins.extras.lang.python",
"lazyvim.plugins.extras.lang.typescript",
"lazyvim.plugins.extras.lang.json",
"lazyvim.plugins.extras.lang.markdown",
"lazyvim.plugins.extras.lang.yaml",
"lazyvim.plugins.extras.lang.toml",
"lazyvim.plugins.extras.lang.docker"
]
}Install the plugins headlessly. This pulls all 38 plugins without opening a window.
nvim --headless "+Lazy! sync" +qa
Install the language tools. A plain MasonInstall failed here with E492: Not an editor command: Mason is lazy-loaded, so its commands don't exist yet when Neovim starts headless. Loading it first fixes that.
nvim --headless -c "Lazy! load mason.nvim" \
-c "MasonInstall lua-language-server pyright ruff vtsls json-lsp marksman \
markdownlint-cli2 markdown-toc yaml-language-server taplo \
dockerfile-language-server docker-compose-language-service hadolint" -c qallCompile the parsers. Otherwise they build during the first launch while you wait.
nvim --headless -c "Lazy! load nvim-treesitter" \
-c "lua require('nvim-treesitter').install({'python','lua','typescript','tsx', ...}):wait(600000)" -c qaCheck its health. :checkhealth lazyvim came back clean: Neovim ≥ 0.11.2, git, rg, fd, lazygit, fzf, curl, a C compiler and the tree-sitter CLI all found.
nvim "+checkhealth lazyvim"
What's installed
The 15 tools in Mason
pyrightruffvtslslua-language-serverstyluashfmtjson-lspyaml-language-servertaplomarksmanmarkdownlint-cli2markdown-tocdockerfile-language-serverdocker-compose-language-servicehadolintThey live in ~/.local/share/nvim/mason/, each in its own folder. Nothing lands in /usr/local or your global npm. Open Space c m to update or add more.
Where the config lives
~/.config/nvim/ ├── init.lua -- loads lua/config/lazy.lua ├── lazyvim.json -- the extras you turned on └── lua/ ├── config/ │ ├── options.lua -- vim.opt settings │ ├── keymaps.lua -- your own mappings │ ├── autocmds.lua │ └── lazy.lua -- plugin manager bootstrap └── plugins/ -- one file per plugin you add or override
The keys worth learning first
Space is the leader key. Press it and wait a moment: which-key shows everything that follows, so you rarely need a cheat sheet for long.
| KEYS | WHAT IT DOES |
|---|---|
| Space Space | Find a file by name |
| Space / | Search text across the project (ripgrep) |
| Space e | Toggle the file tree |
| Space , | Switch between open buffers |
| g d · g r · K | Go to definition · references · show docs |
| Space c a | Code action (quick fix) |
| Space c r | Rename a symbol everywhere |
| Space x x | All diagnostics in a list |
| Space g g | lazygit, full screen |
| Space l · Space c m | Plugins · language tools |
Things that tripped us up
LazyVim's file icons, git symbols and status line glyphs are Nerd Font characters. With a terminal font like SF Mono they show as empty boxes. The fix doesn't need a new terminal font: list a Nerd Font after your usual one (here, "SF Mono", Menlo, "JetBrainsMono Nerd Font Mono", monospace) and the terminal falls back to it for the icons only.
Run without a window, several plugins report "setup did not run" and image previews complain about kitty, ImageMagick, Ghostscript and LaTeX. Those are optional. The section that matters is lazyvim, and it was all green.
An alias only changes what your shell runs. Scripts that call /usr/bin/vim by path still get the stock one, and that's fine.
Where to go next
Open :LazyExtras to add more languages (Go, Rust, Tailwind…) or editor extras. Put personal settings in lua/config/options.lua rather than editing plugins. Each file in lua/plugins/ returns a spec that LazyVim merges with its own, so overriding a plugin is usually three lines. And when something feels slow, :Lazy profile shows exactly which plugin is to blame.
Comments
Post a Comment