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:

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)