⛶  base.nvim  ⛶

---

Writing a Neovim plugin has become very easy. Lua rocks! (pun intended), busted, LuaLS, and CI/CD pipelines make the development process a breeze.

1. Choose a name with the extension .nvim, e.g., your-plugin.nvim.
2. On the top right of this page, click on Use this template > Create a new repository with that name.
3. Clone your new repo and cd into it.
4. Rename base to your-plugin in the whole repo.
5. Rename S1M0N38 to your-github-username in the whole repo.

🛠️ Setup

• Neovim (≥ 0.10)

• luarocks, busted, and nlua (macOS install.sh and uninstall.sh scripts)

• lazy.nvim and lazydev.nvim

{
  {
    "base.nvim",
    dir = "/path/to/base.nvim",
    lazy = false,
    opts = {},
    keys = {
      {
        "<leader>rb",
        "<cmd>Lazy reload base.nvim<cr>",
        desc = "Reload base.nvim",
        mode = { "n", "v" },
      },
    },
  },

  {
    "folke/lazydev.nvim",
    ft = "lua",
    opts = {
      library = {
        "${3rd}/luassert/library",
        "${3rd}/busted/library",
        "base.nvim",
      }
    },
  },
}

📁 Plugin Structure

• plugin/base.lua - the main file, the one loaded by the plugin manager.

• spec/base_spec.lua - plugin tests. Add other _spec.lua files here for further testing.

• lua/base/

  • init.lua - the main file of the plugin, the one loaded by plugin/base.lua.
  • health.lua - run checks of the plugin when :checkhealth base is called.
  • types.lua - a definition file where LuaCATS annotations are defined.

🔍 Lua Language Server

Lua Language Server (LuaLS) is a language server providing autocompletion, hover, diagnostics, annotations support, formatting. The lazydev.nvim plugin takes care of configuring it properly.

• .editorconfig - file format for defining coding styles (cross-editor).

🧪 Tests

Busted is a unit testing framework for Lua. Using nlua as Lua interpreter gives you access to Neovim Lua API while running tests. To run tests, simply run busted from the root of the plugin.

• .busted - configuration file for Busted which specifies nlua as the Lua interpreter.

📚 Documentation

It's important to document your plugin in the Vim/Neovim way so it's easily accessible from within the editor.

• doc/base.txt - documentation file for the plugin formatted as vimdoc.

📦 CI/CD

It's no secret that the Neovim plugin ecosystem can be brittle. Prove them wrong with:

• .github/workflows/
  • run-tests.yml - workflow to run tests on every push to the main branch.
  • run-typecheck.yml - workflow to typecheck code on every push.
  • release-github.yml - workflow to create a new release on GitHub on every push to the main branch.
  • release-luarocks.yml - workflow to create a new release on LuaRocks on every release on GitHub.

Write your commit messages following Conventional Commits specification and let the CI/CD do the rest.

👏 Resources

Neovim is growing a nice ecosystem, but some parts of plugin development are sometimes obscure. This template is an attempt to put together some best practices. Here are sources on which this template is based and that I constantly refer to:

• 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: Add type annotations to your Lua code
• Plugin development walkthrough by TJ DeVries: it uses plenary instead of busted for testing