nvim-lua-plugin-template

This repository is a template for Neovim plugins written in Lua.

The intention is that you use this template to create a new repository where you then adapt this readme and add your plugin code. The template includes the following:

• GitHub workflows and configurations to run linters and tests
• Packaging of tagged releases and upload to LuaRocks if a LUAROCKS_API_KEY is added to the GitHub Actions secrets
• Minimal test setup:
  • A scm rockspec, nvim-lua-plugin-scm-1.rockspec
  • A .busted file
• EditorConfig
• A .luacheckrc

To get started writing a Lua plugin, I recommend reading :help lua-guide and :help write-plugin.

Scope

Anything that the majority of plugin authors will want to have is in scope of this starter template. Anything that is controversial is out-of-scope.

Usage

• Click Use this template. Do not fork.
• Rename nvim-lua-plugin-scm-1.rockspec and change the package name to the name of your plugin.

Template License

The template itself is licensed under the MIT license. The template doesn't include a LICENSE file. You should add one after creating your repository.

---

The remainder of the README is text that can be preserved in your plugin:

---

Development

Run tests

Running tests requires either

• luarocks
• or busted and nlua

to be installed¹.

You can then run:

luarocks test --local
# or
busted

Or if you want to run a single test file:

luarocks test spec/path_to_file.lua --local
# or
busted spec/path_to_file.lua

Common Errors

"module "busted.runner" not found" or "pl.path requires LuaFileSystem" Error

If you see one of the errors like the above fix it by runing the following command the following command:

eval $(luarocks path --no-bin)

"sh: nlua: command not found" Error

If the error above occurs do¹:

Linux/Max

Run the following command:

export PATH=$PATH:~/.luarocks/bin

Windows

See the following guide to a variable to the PATH: add to PATH.

Note

For local testing to work you need to have Lua 5.1 set as your default version for luarocks. If that's not the case you can pass --lua-version 5.1 to all the luarocks commands above, or set lua version 5.1 globally by running luarocks config --scope system lua_version 5.1.

Footnotes

1. The test suite assumes that nlua has been added to the PATH. ↩ ↩²