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)