README.md

September 15, 2025 · View on GitHub


rocks-lazy.nvim


Report Bug · Request Feature · Ask Question

A lazy-loading module for rocks.nvim!

LuaRocks

:star2: Summary

rocks-lazy.nvim is a rocks.nvim module that helps you lazy-load your rocks.nvim plugins using the 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.

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.

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:

[plugins.nvim-cmp]
version = "scm"
event = "InsertEnter"

[plugins]
nvim-cmp = { version = "scm", event = "InsertEnter" }

cmd

Lazy-load on a command (:h user-commands).

  • Type: string? or string[]

Example:

[plugins."telescope.nvim"]
version = "0.1.8"
cmd = "Telescope"

[plugins]
"telescope.nvim" = { version = "0.1.8", cmd = "Telescope" }

ft

Lazy-load on a :h filetype event.

  • Type: string? or string[]

Example:

[plugins.neorg]
version = "8.0.0"
ft = "norg"

[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

Examples:

[plugins."neo-tree.nvim"]
version = "scm"
keys = { lhs = "<leader>ft", rhs = "<CMD>Neotree toggle<CR>", desc = "NeoTree toggle" }

[plugins."dial.nvim"]
version = "0.4.0"
keys = ["<C-a>", { lhs = "<C-x>", mode = "n" }]

[plugins]
"neo-tree.nvim" = { version = "scm", keys = { "<leader>ft", "<CMD>Neotree toggle<CR>", desc = "NeoTree toggle" } }

colorscheme

Lazy-load when setting a colorscheme.

  • Type: string? or string[]

Example:

[plugins."kanagawa.nvim"]
version = "1.0.0"
colorscheme = [
  "kanagawa",
  "kanagawa-dragon",
  "kanagawa-lotus",
  "kanagawa-wave"
]

[plugins]
"sweetie.nvim" = { version = "1.0.0", colorscheme = "sweetie" }

Tip

You can specify combinations of the above lazy-loading fields

Example:

[plugins."telescope.nvim"]
version = "0.1.8"
cmd = "Telescope"
keys = [ { lhs = "<leader>t", rhs = "<CMD>Telescope<CR>" } ]

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 in the before hook.
[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.

── 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

── nvim
  ├── lua
  │  └── lazy_specs.lua # Optional top-level module returning a list of specs
  ├── init.lua

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 extend2 the rocks.toml specs with the imported 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.

Tip

If you use Lua to configure lazy-loading, you can invoke the default before hook by calling require("rocks-lazy").default_before_hook(plugin).

:book: License

rocks-lazy.nvim is licensed under GPLv3.

Footnotes

  1. This is because toml tables are stricter than Lua tables. ↩

  2. Duplicate specs in the Lua configs will overwrite existing ones. ↩