Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nvim-neorocks/rocks-lazy.nvim
:sloth: A lazy-loading module for rocks.nvim
https://github.com/nvim-neorocks/rocks-lazy.nvim
lazy-loading luarocks neovim neovim-plugin rocks-nvim
Last synced: 11 days ago
JSON representation
:sloth: A lazy-loading module for rocks.nvim
- Host: GitHub
- URL: https://github.com/nvim-neorocks/rocks-lazy.nvim
- Owner: nvim-neorocks
- License: gpl-3.0
- Created: 2024-06-11T21:37:01.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2024-10-15T17:40:49.000Z (about 1 month ago)
- Last Synced: 2024-10-29T21:38:07.041Z (19 days ago)
- Topics: lazy-loading, luarocks, neovim, neovim-plugin, rocks-nvim
- Language: Lua
- Homepage:
- Size: 77.1 KB
- Stars: 31
- Watchers: 3
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[![LuaRocks][luarocks-shield]][luarocks-url]
## :star2: Summary
`rocks-lazy.nvim` is a rocks.nvim module that helps you lazy-load
your rocks.nvim plugins using
the [`lz.n`](https://github.com/nvim-neorocks/lz.n) library.
> [!NOTE]
>
> **Should I lazy-load plugins?**
>
> It should be a plugin author's responsibility to ensure their plugin doesn't
> unnecessarily impact startup time, not yours!
>
> See [our "DO's and DONT's" guide for plugin developers](https://github.com/nvim-neorocks/nvim-best-practices?tab=readme-ov-file#sleeping_bed-lazy-loading).
>
> Regardless, the current status quo is horrible, and some authors may
> not have the will or capacity to improve their plugins' startup impact.
>
> If you find a plugin that takes too long to load,
> or worse, forces you to load it manually at startup with a
> call to a heavy `setup` function,
> consider opening an issue on the plugin's issue tracker.
> [!IMPORTANT]
>
> With luarocks, *libraries* do not have a meaningful impact on startup time
> and [don't need to be lazy-loaded](https://github.com/nvim-neorocks/rocks.nvim?tab=readme-ov-file#a-note-on-loading-rocks).
>
> This plugin handles lazy-loading of *plugin* initialization scripts.
## :pencil: Requirements
- An up-to-date `rocks.nvim`.
## :hammer: Installation
Simply run `:Rocks install rocks-lazy.nvim`,
and you are good to go!
## :books: Usage
### Via `rocks.toml`
With this module installed, you can add the fields that tell `rocks-lazy.nvim`
how to lazy-load to a `[plugins]` entry in your `rocks.toml`.
#### `event`
Lazy-load on an event (`:h autocmd-events`).
- Type: `string?` or `string[]`
Events can be specified with or without patterns, e.g.
`BufEnter` or `BufEnter *.lua`.
Example:
```toml
[plugins.nvim-cmp]
version = "scm"
event = "InsertEnter"
```
```toml
[plugins]
nvim-cmp = { version = "scm", event = "InsertEnter" }
```
#### `cmd`
Lazy-load on a command (`:h user-commands`).
- Type: `string?` or `string[]`
Example:
```toml
[plugins."telescope.nvim"]
version = "0.1.8"
cmd = "Telescope"
```
```toml
[plugins]
"telescope.nvim" = { version = "0.1.8", cmd = "Telescope" }
```
#### `ft`
Lazy-load on a `:h filetype` event.
- Type: `string?` or `string[]`
Example:
```toml
[plugins.neorg]
version = "8.0.0"
ft = "norg"
```
```toml
[plugins]
neorg = { version = "8.0.0", ft = "norg" }
```
#### `keys`
Lazy-load on key mappings.
- Type: `string?` or `string[]` or `rocks.lazy.KeysSpec[]`
Where `rocks.lazy.KeysSpec` is a table with the following fields:
- `lhs`: `string`
- `rhs`: `string?`
- `mode`: `string?` or `string[]` (default: `"n"`)
- `[string]`: Options, see `:h vim.keymap.set`
> [!NOTE]
>
> - If unspecified, the default `mode` is `n`.
> - The `lhs` and `rhs` fields differ
> from [the `lz.n.PluginSpec`](https://github.com/nvim-neorocks/lz.n?tab=readme-ov-file#plugin-spec)[^1].
[^1]: This is because toml tables are stricter than Lua tables.
Examples:
```toml
[plugins."neo-tree.nvim"]
version = "scm"
keys = { lhs = "ft", rhs = "Neotree toggle", desc = "NeoTree toggle" }
[plugins."dial.nvim"]
version = "0.4.0"
keys = ["", { lhs = "", mode = "n" }]
```
```toml
[plugins]
"neo-tree.nvim" = { version = "scm", keys = { "ft", "Neotree toggle", desc = "NeoTree toggle" } }
```
#### `colorscheme`
Lazy-load when setting a colorscheme.
- Type: `string?` or `string[]`
Example:
```toml
[plugins."kanagawa.nvim"]
version = "1.0.0"
colorscheme = [
"kanagawa",
"kanagawa-dragon",
"kanagawa-lotus",
"kanagawa-wave"
]
```
```toml
[plugins]
"sweetie.nvim" = { version = "1.0.0", colorscheme = "sweetie" }
```
> [!TIP]
>
> You can specify combinations of the above lazy-loading fields
>
> Example:
>
> ```toml
> [plugins."telescope.nvim"]
> version = "0.1.8"
> cmd = "Telescope"
> keys = [ { lhs = "t", rhs = "Telescope" } ]
> ```
>
> Whichever event occurs first will load the plugin.
### Lua configuration
If you prefer using Lua for configuration,
you can add a `import` option to your `rocks.toml`:
> [!IMPORTANT]
>
> - If you use Lua to configure lazy-loading, you must set `opt = true`
> in your rocks.toml entries.
> - Lua specs do not automatically
> integrate with rocks-config.nvim.
> You [can do so manually](https://github.com/nvim-neorocks/rocks-config.nvim?tab=readme-ov-file#load_opt_plugins)
> in the `before` hook.
```toml
[rocks_lazy]
import = "lazy_specs/"
```
This is a subdirectory (relative to `nvim/lua`)
to search for plugin specs.
In this example, you can add a `lua/lazy_specs/` directory
to your `nvim` config, with a lua script for each plugin.
```sh
── nvim
├── lua
│ └── lazy_specs # Your plugin specs go here.
│ └── init.lua # Optional top-level module returning a list of specs
│ └── neorg.lua # Single spec
│ └── sweetie.lua
├── init.lua
```
Or
```sh
── nvim
├── lua
│ └── lazy_specs.lua # Optional top-level module returning a list of specs
├── init.lua
```
- See [the `lz.n` documentation](https://github.com/nvim-neorocks/lz.n?tab=readme-ov-file#structuring-your-plugins).
- The Lua plugins specs must be configured according to
the [`lz.n.PluginSpec`](https://github.com/nvim-neorocks/lz.n?tab=readme-ov-file#plugin-spec).
> [!IMPORTANT]
>
> If you use a module to import your plugin specs
> and you also use `rocks-config.nvim`,
> the `rocks-lazy` `import` module name
> **must not clash** with the `rocks-config` `plugins_dir`.
> [!TIP]
>
> You can use both `rocks.toml` entries and a Lua config to configure
> your plugin specs.
> `rocks-lazy.nvim` will extend[^2] the rocks.toml specs with the imported ones.
[^2]: Duplicate specs in the Lua configs will overwrite existing ones.
## :electric_plug: `rocks-config` interoperability
If you are using `rocks-config.nvim >= 2.0.0`,
it will not load configs for any `opt` plugins.
`rocks-lazy` will use the `rocks-config` API to load them in the
`lz.n.PluginSpec.before` hooks.
## :book: License
`rocks-lazy.nvim` is licensed under [GPLv3](./LICENSE).
[luarocks-shield]: https://img.shields.io/luarocks/v/neorocks/rocks-lazy.nvim?logo=lua&color=purple&style=for-the-badge
[luarocks-url]: https://luarocks.org/modules/neorocks/rocks-lazy.nvim
