Back to Details

effective-neovim

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Effective Neovim

高效开发Neovim Lua插件

Apply best practices from the Neovim community to write clean, idiomatic Lua plugins.
遵循Neovim社区的最佳实践，编写简洁、符合Lua惯用风格的插件。

When to Apply

适用场景

Use this skill automatically when:
  • Writing new Neovim plugins in Lua
  • Reviewing Neovim plugin code
  • Refactoring existing plugin implementations
在以下场景下自动使用本技能：
  • 编写全新的基于Lua的Neovim插件
  • 评审Neovim插件代码
  • 重构现有插件的实现

Tooling

工具链

The Type A Neovim developers use:
ToolPurpose
StyLuaFormatter (opinionated, like prettier)
seleneLinter (30+ checks)
lua-language-serverType checking via LuaCATS annotations
Neovim's own 
.stylua.toml
:
toml
column_width = 100
indent_type = "Spaces"
indent_width = 2
quote_style = "AutoPreferSingle"
顶尖Neovim开发者使用的工具：
工具用途
StyLua代码格式化工具（带主观配置，类似prettier）
selene代码检查工具（包含30+项检查）
lua-language-server通过LuaCATS注解实现类型检查
Neovim官方的
.stylua.toml
配置：
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
    .
来自nvim-best-practices（部分内容已被纳入
:h lua-plugin
帮助文档）：
  • 不强制要求
    setup()
    ：插件应开箱即用。将配置与初始化分离。
  • 使用
    <Plug>
    映射    ：让用户自定义快捷键，而非硬编码绑定。
  • 子命令优于命名污染：使用
    :Rocks install
    而非
    :RocksInstall
    、
    :RocksPrune
    等形式。
  • 延迟
    require()
    加载    ：不要在启动时加载所有模块。在命令实现内部再引入模块。
  • LuaCATS注解：使用类型提示；在CI流程中通过lua-language-server捕获bug。
  • 优先使用Busted而非plenary.nvim：用于测试。功能更强大，在Lua社区更通用。
  • 语义化版本（SemVer）：为插件正确标记版本。发布至luarocks.org。
  • 健康检查：提供
    lua/{plugin}/health.lua
    文件以支持
    :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
  • 缩进：2个空格（不使用制表符）
  • 引号：优先使用单引号
  • 行宽：100列
  • 命名：函数和变量使用
    snake_case
    ，类/模块使用
    PascalCase
  • 不使用分号：Lua中不需要分号
  • 多行表使用尾随逗号：让Diff更清晰
  • 注释：解释“为什么”，而非“是什么”

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
plugin-name/
├── lua/
│   └── plugin-name/
│       ├── init.lua      # 入口文件，包含setup函数
│       ├── health.lua    # 集成:checkhealth命令
│       └── *.lua         # 模块文件
├── plugin/
│   └── plugin-name.lua   # 自动加载，定义命令/自动命令
├── doc/
│   └── plugin-name.txt   # 用于:h plugin-name的Vimdoc文档
└── tests/
    └── *_spec.lua        # Busted测试文件

References

参考资料

For detailed guidance with code examples, see 
references/nvim-best-practices.md
.
External sources:
如需包含代码示例的详细指导，请查看
references/nvim-best-practices.md
。
外部资源：