Neovim Best Practices

Opinionated guidance for modern Neovim configuration. This skill covers the decisions and patterns that matter — not documentation you can look up.

Core Decisions

These are the opinionated choices this config follows. Apply these unless the user explicitly wants something different.

Lua Only, No Vimscript

All configuration in Lua. No vim.cmd() wrappers around Vimscript unless there's no Lua API equivalent. Use vim.opt for options, vim.keymap.set for keymaps, vim.api.nvim_create_autocmd for autocommands.

lazy.nvim for Plugin Management

One plugin per file in lua/plugins/. Every plugin lazy-loaded unless needed at startup (colorscheme, treesitter, statusline). See the lazy-nvim-optimization skill for deep lazy-loading guidance.

Namespace Under Username

~/.config/nvim/
├── init.lua
└── lua/
    └── kriscard/
        ├── init.lua
        ├── options.lua
        ├── keymaps.lua
        ├── autocmds.lua
        └── lazy.lua

This prevents collisions with plugin module names. Entry point is just require("kriscard").

LSP via Mason + nvim-lspconfig

Mason manages server installations. nvim-lspconfig provides server configurations. Use cmp_nvim_lsp capabilities for completion integration. Set keymaps in on_attach so they're buffer-local.

Leader Key Conventions

<Space> as leader, set before any plugins load. Organized by prefix:

f = find/search (telescope)
g = git operations
b = buffer management
w = window management
l = LSP operations
t = terminal/tests

Every keymap requires a desc field for which-key discoverability.

Version-Specific Features (0.10+)

Take advantage of these — they replace plugins:

Built-in commenting: gcc/gc work natively. Can replace Comment.nvim.
Inlay hints: vim.lsp.inlay_hint.enable(true) — no plugin needed.
Improved diagnostics: vim.diagnostic.config() with float.border for better display.

Deprecated Patterns to Avoid

Instead of...	Use...
`vim.cmd("set number")`	`vim.opt.number = true`
`vim.api.nvim_set_keymap()`	`vim.keymap.set()`
`vim.cmd("augroup...")`	`vim.api.nvim_create_autocmd()`
Vimscript autocommands	Lua with `callback`
Comment.nvim (on 0.10+)	Built-in `gcc`

Checklists

Config Structure

init.lua is entry point only (just require("kriscard"))
Config namespaced under username in lua/
Plugin specs in lua/plugins/ (one per file or logical group)
Options, keymaps, autocmds in separate files
Using lazy.nvim for plugin management

Code Quality

All config in Lua (no Vimscript)
vim.opt for options
vim.keymap.set with desc for keymaps
vim.api.nvim_create_autocmd for autocommands
No deprecated APIs
Leader key set before plugin loading

Performance

Startup under 50ms (nvim --startuptime)
Plugins lazy-loaded by cmd/keys/ft/event
Heavy plugins deferred with VeryLazy
No synchronous system calls at startup

Reference Files

For detailed information:

references/plugin-recommendations.md - Curated plugin list by category
references/lsp-setup.md - Comprehensive LSP configuration guide
references/migration-guide.md - Migrating from Vimscript to Lua

neovim-best-practices