Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/s1m0n38/base.nvim
A template for Neovim plugin 🛠️
https://github.com/s1m0n38/base.nvim
neovim nvim-plugin template
Last synced: about 2 months ago
JSON representation
A template for Neovim plugin 🛠️
- Host: GitHub
- URL: https://github.com/s1m0n38/base.nvim
- Owner: S1M0N38
- License: mit
- Created: 2024-01-10T21:58:43.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-09-15T19:35:20.000Z (4 months ago)
- Last Synced: 2024-09-16T20:10:34.008Z (4 months ago)
- Topics: neovim, nvim-plugin, template
- Language: Lua
- Homepage:
- Size: 16.9 MB
- Stars: 49
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
⛶ 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`.
1. On the top right of this page, click on `Use this template` > `Create a new repository` with that name.
1. Clone your new repo and `cd` into it.
1. Rename `base` to `your-plugin` in the whole repo.
1. Rename `S1M0N38` to `your-github-username` in the whole repo.
### 🛠️ Setup
- **Neovim** (≥ 0.10)
- **[luarocks](https://luarocks.org/)**, **[busted](https://lunarmodules.github.io/busted/)**, and **[nlua](https://github.com/mfussenegger/nlua)** (macOS [install.sh](https://gist.githubusercontent.com/S1M0N38/44c573db63864bcd1dc0bfc73359fec9/raw/d92e3b3e5f3da1c8557e93250e6e8a7de0f7d09a/install-lua-luarocks-on-macos.sh) and [uninstall.sh](https://gist.githubusercontent.com/S1M0N38/44c573db63864bcd1dc0bfc73359fec9/raw/d92e3b3e5f3da1c8557e93250e6e8a7de0f7d09a/uninstall-lua-luarocks-on-macos.sh) scripts)
- **[lazy.nvim](https://github.com/folke/lazy.nvim)** and **[lazydev.nvim](https://github.com/folke/lazydev.nvim)**
```lua
{
{
"base.nvim",
dir = "/path/to/base.nvim",
lazy = false,
opts = {},
keys = {
{
"rb",
"Lazy reload base.nvim",
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](https://luals.github.io/wiki/definition-files/) where LuaCATS annotations are defined.
### 🔍 Lua Language Server
[Lua Language Server](https://github.com/luals/lua-language-server?tab=readme-ov-file) (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](https://lunarmodules.github.io/busted/) is a unit testing framework for Lua. Using [nlua](https://github.com/mfussenegger/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](https://www.conventionalcommits.org/en/v1.0.0/) 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](https://github.com/nvim-neorocks/nvim-best-practices): Collection of DOs and DON'Ts for modern Neovim Lua plugin development
- [nvim-lua-plugin-template](https://github.com/nvim-lua/nvim-lua-plugin-template/): Another template for Neovim Lua plugins
- [LuaCATS annotations](https://luals.github.io/wiki/annotations/): Add type annotations to your Lua code
- [Plugin development walkthrough](https://youtu.be/n4Lp4cV8YR0?si=lHlxQBNvbTcXPhVY) by [TJ DeVries](https://github.com/tjdevries): it uses plenary instead of busted for testing