Effective Neovim

Apply best practices from the Neovim community to write clean, idiomatic Lua plugins.

When to Apply

Use this skill automatically when:

Writing new Neovim plugins in Lua
Reviewing Neovim plugin code
Refactoring existing plugin implementations

Tooling

The Type A Neovim developers use:

| Tool | Purpose | | ------ | --------- | | StyLua | Formatter (opinionated, like prettier) | | selene | Linter (30+ checks) | | lua-language-server | Type checking via LuaCATS annotations |

Neovim's own .stylua.toml:

column_width = 100
indent_type = "Spaces"
indent_width = 2
quote_style = "AutoPreferSingle"

Key Principles

From nvim-best-practices (parts upstreamed to :h lua-plugin):

No forced setup(): Plugins should work out of the box. Separate configuration from initialization.
<Plug> mappings: Let users define their own keymaps instead of hardcoding bindings.
Subcommands over pollution: Use :Rocks install not :RocksInstall, :RocksPrune, etc.
Defer require(): Don't load everything at startup. Require inside command implementations.
LuaCATS annotations: Use type hints; catch bugs in CI with lua-language-server.
Busted over plenary.nvim: For testing. More powerful, standard in broader Lua community.
SemVer: Version your plugins properly. Publish to luarocks.org.
Health checks: Provide lua/{plugin}/health.lua for :checkhealth.

Style Conventions

Indent: 2 spaces (not tabs)
Quotes: Single quotes preferred
Line width: 100 columns
Naming: snake_case for functions and variables, PascalCase for classes/modules
No semicolons: They're unnecessary in Lua
Trailing commas: In multi-line tables for cleaner diffs
Comments: Explain why, not what

Plugin Structure

plugin-name/
├── lua/
│   └── plugin-name/
│       ├── init.lua      # Entry point, setup function
│       ├── health.lua    # :checkhealth integration
│       └── *.lua         # Module files
├── plugin/
│   └── plugin-name.lua   # Auto-loaded, defines commands/autocommands
├── doc/
│   └── plugin-name.txt   # Vimdoc for :h plugin-name
└── tests/
    └── *_spec.lua        # Busted test files

References

For detailed guidance with code examples, see references/nvim-best-practices.md.

External sources:

nvim-best-practices: https://github.com/nvim-neorocks/nvim-best-practices
Neovim Lua Guide: :h lua-guide
Plugin Development: :h lua-plugin
Roblox Style Guide: https://roblox.github.io/lua-style-guide/ (StyLua's basis)