⛶  base.nvim  ⛶

A template for writing Neovim plugins

---

💡 Motivation

A minimal Neovim plugin is just a lua/ directory and a plugin/ autocommand. But a maintainable one needs tests, docs, types, CI, and a release workflow. base.nvim fills that gap — no framework, no abstraction, just the smallest possible set of opinionated defaults that work.

Starting a plugin shouldn't mean reinventing project structure and CI pipelines from scratch. base.nvim bundles the conventions used in production plugins so you can focus on writing plugin logic from day one:

• Proper directory layout following nvim-best-practices
• LuaCATS type annotations with LuaLS checking
• mini.test + luassert test suite
• StyLua formatting and linting
• CI with lint, typecheck, and test (stable + nightly)
• Automated releases via release-please with GitHub and LuaRocks publishing
• Health checks and vimdoc documentation
• Agent Skills for AI-assisted development

⚡️ Requirements

• Neovim ≥ 0.12.2
• StyLua: code formatting and linting
• LuaLS: type checking via LuaCATS annotations
• git: version control and lazy.nvim bootstrap
• Make: task runner for build and test commands

Optional:

• lazydev.nvim: Lua LSP configuration for plugin development

📦 Installation

1. Ensure you have requirements installed
2. Click "Use this template" → "Create a new repository" at the top of this page.
3. Choose a name with the .nvim extension (e.g., your-plugin.nvim).
4. Clone your new repository and cd into it.
5. Install your-plugin.nvim using your preferred plugin manager and configure Neovim for plugin development:

-- Install and configure your plugin during development
{
  "your-plugin.nvim",
  dir = "/path/to/your-plugin.nvim", -- So we are using the local version of the plugin
  branch = "main", -- Select the branch of the plugin to use
  lazy = false,
  opts = {},
  keys = {
    {
      "<leader>rb", -- Choose a key binding for reloading the plugin
      "<cmd>Lazy reload your-plugin.nvim<cr>",
      desc = "Reload your-plugin.nvim",
      mode = { "n", "v" },
    },
  },
}

-- Enable Lua language server support external libraries
{
  "folke/lazydev.nvim",
  ft = "lua",
  opts = {
    library = {
      "your-plugin.nvim",
    }
  },
}

🤖 AI Coding Agent

This template ships with Agent Skills in .agents/skills/, providing specialized instructions for AI coding agents. Skills follow the Agent Skills specification — the same SKILL.md format works across many agents (e.g. pi, Claude Code, GitHub Copilot, Cursor, Amp). Note that agents discover skills from different directories (e.g. .claude/skills/, .github/skills/). If your agent doesn't pick them up, try renaming .agents/ to its expected directory (e.g. mv .agents .claude for Claude Code).

Skill	Description
nvim-plugin	Plugin development best practices and patterns
nvim-test	Execute tests and diagnose failures
nvim-doc	Write and update vimdoc help documentation
nvim-commit	Create conventional commits for release-please
nvim-help	Search Neovim's built-in :help documentation

🚀 Usage

Get started by reading the comprehensive documentation with :help base, which covers all plugin features and configuration options.

Note

Most Vim/Neovim plugins include built-in :help documentation. If you're new to this, start with :help to learn the basics.

🙏 Acknowledgments

• nvim-best-practices: Collection of DOs and DON'Ts for modern Neovim Lua plugin development
• nvim-lua-plugin-template: another template for Neovim Lua plugins
• LuaCATS annotations: type annotations to your Lua code
• mini.test: minimal test framework with child-process isolation