Awesome
<!-- markdownlint-disable --> <br /> <div align="center"> <a href="https://github.com/nvim-neorocks/rocks-lazy.nvim"> <img src="./rocks-header.svg" alt="rocks-lazy.nvim"> </a> <p align="center"> <!-- <br /> --> <!-- <a href="./doc/rocks-lazy.txt"><strong>Explore the docs »</strong></a> --> <!-- <br /> --> <br /> <a href="https://github.com/nvim-neorocks/rocks-lazy.nvim/issues/new?assignees=&labels=bug">Report Bug</a> · <a href="https://github.com/nvim-neorocks/rocks-lazy.nvim/issues/new?assignees=&labels=enhancement">Request Feature</a> · <a href="https://github.com/nvim-neorocks/rocks.nvim/discussions/new?category=q-a">Ask Question</a> </p> <p> <strong> A lazy-loading module for <a href="https://github.com/nvim-neorocks/rocks.nvim/">rocks.nvim</a>! </strong> </p> </div> <!-- markdownlint-restore -->: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?
orstring[]
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?
orstring[]
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?
orstring[]
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?
orstring[]
orrocks.lazy.KeysSpec[]
Where rocks.lazy.KeysSpec
is a table with the following fields:
lhs
:string
rhs
:string?
mode
:string?
orstring[]
(default:"n"
)[string]
: Options, see:h vim.keymap.set
[!NOTE]
- If unspecified, the default
mode
isn
.- The
lhs
andrhs
fields differ from thelz.n.PluginSpec
1.
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?
orstring[]
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
- See the
lz.n
documentation. - The Lua plugins specs must be configured according to
the
lz.n.PluginSpec
.
[!IMPORTANT]
If you use a module to import your plugin specs and you also use
rocks-config.nvim
, therocks-lazy
import
module name must not clash with therocks-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.
:book: License
rocks-lazy.nvim
is licensed under GPLv3.