A dead simple lazy-loading Lua library for Neovim plugins.
It is intended to be used
[!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.
:h autocmd-events
)FileType
events:h packpath
(:h packadd
)lz.n
provides abstractions for lazy-loading Neovim plugins,
with an API that is loosely based on lazy.nvim
,
but reduced down to the very basics required for lazy-loading only.
lz.n
is designed based on the UNIX philosophy: Do one thing well.
lazy.nvim
lz.n
is not a plugin manager, but focuses on lazy-loading only.
It is intended to be used with (or by) a plugin manager.lazy.nvim
features are out of scope:
lazy.vim
completely disables and takes over Neovim's
built-in loading mechanisms, including
adding a plugin's API (lua
, autoload
, ...)
to the runtimepath.
lz.n
doesn't.
Its only concern is plugin initialization, which is
the bulk of the startup overhead.require
.lz.n
provides a colorscheme
handler in the plugin spec.main
module and automatically calling
a setup()
function.opts
table.
lz.n
provides simple hooks that you can use to specify
when to load configurations.Neovim >= 0.10.0
You can override the function used to load plugins.
lz.n
has the following default:
vim.g.lz_n = {
---@type fun(name: string)
load = vim.cmd.packadd,
}
require("lz.n").load(plugins)
table
or a string
table
:string
: a Lua module name that contains your Plugin Spec.
See Structuring Your Plugins[!TIP]
You can call
load()
as you would calllazy.nvim
'ssetup()
. Or, you can also use it to register individual plugin specs for lazy loading.
Property | Type | Description | lazy.nvim equivalent |
---|---|---|---|
[1] | string |
The plugin's name (not the module name). This is what is passed to the load(name) function. |
name [^1] |
enabled | boolean? or fun():boolean |
When false , or if the function returns false, then this plugin will not be included in the spec. |
enabled |
beforeAll | fun(lz.n.Plugin)? |
Always executed before any plugins are loaded. | init |
before | fun(lz.n.Plugin)? |
Executed before a plugin is loaded. | None |
after | fun(lz.n.Plugin)? |
Executed after a plugin is loaded. | config |
event | string? or {event?:string\|string[], pattern?:string\|string[]}\ or string[] |
Lazy-load on event. Events can be specified as BufEnter or with a pattern like BufEnter *.lua . |
event |
cmd | string? or string[] |
Lazy-load on command. | cmd |
ft | string? or string[] |
Lazy-load on filetype. | ft |
keys | string? or string[] or lz.n.KeysSpec[] |
Lazy-load on key mapping. | keys |
colorscheme | string? or string[] |
Lazy-load on colorscheme. | None. lazy.nvim lazy-loads colorschemes automatically[^2]. |
priority | number? |
Only useful for start plugins (not lazy-loaded) to force loading certain plugins first. Default priority is 50 (or 1000 if colorscheme is set). |
priority |
load | fun(string)? |
Can be used to override the vim.g.lz_n.load() function for an individual plugin. |
None. |
[^1]: In contrast to lazy.nvim
's name
field, a lz.n.PluginSpec
's name
is not optional.
This is because lz.n
is not a plugin manager and needs to be told which
plugins to load.
[^2]: The reason this library doesn't lazy-load colorschemes automatically is that
it would have to know where the plugin is installed in order to determine
which plugin to load.
DeferredUIEnter
: Triggered when load()
is done and after UIEnter
.
Can be used as an event
to lazy-load plugins that are not immediately needed
for the initial UI[^3].[^3]: This is equivalent to lazy.nvim
's VeryLazy
event.
require("lz.n").load {
{
"neo-tree.nvim",
keys = {
-- Create a key mapping and lazy-load when it is used
{ "<leader>ft", "<CMD>Neotree toggle<CR>", desc = "NeoTree toggle" },
},
after = function()
require("neo-tree").setup()
end,
},
{
"crates.nvim",
-- lazy-load when opening a toml file
ft = "toml",
},
{
"sweetie.nvim",
-- lazy-load when setting the `sweetie` colorscheme
colorscheme = "sweetie",
},
{
"vim-startuptime",
cmd = "StartupTime",
before = function()
-- Configuration for plugins that don't force you to call a `setup` function
-- for initialization should typically go in a `before`
--- or `beforeAll` function.
vim.g.startuptime_tries = 10
end,
},
{
"nvim-cmp",
-- load cmp on InsertEnter
event = "InsertEnter",
},
{
"dial.nvim",
-- lazy-load on keys. -- Mode is `n` by default.
keys = { "<C-a>", { "<C-x>", mode = "n" } },
},
}
As is the case with lazy.nvim
, you can also split your plugin specs
into multiple files.
Instead of passing a spec table to load()
, you can use a Lua module.
The function will merge specs from the module and any top-level sub-modules
together in the final spec, so it is not needed to add require
calls
in your main plugin file to the other files.
Example:
~/.config/nvim/init.lua
require("lz.n").load("plugins")
~/.config/nvim/lua/plugins.lua
or ~/.config/nvim/lua/plugins/init.lua
(this file is optional)return {
{ "sweetie.nvim" },
{ "telescope.nvim", cmd = "Telescope" },
}
lz.n
will automatically merge any Lua file in ~/.config/nvim/lua/plugins/*.lua
with the main plugin spec[^4].[^4]: It does not merge multiple specs for the same plugin from different files.
Example structure:
ββ nvim
βββ lua
β βββ plugins # Your plugin specs go here.
β βββ init.lua # Optional top-level module returning a list of specs
β βββ neorg.lua # Single spec
β βββ telescope/init.lua # Single spec
βββ init.lua
Or
ββ nvim
βββ lua
β βββ plugins.lua # Optional top-level module returning a list of specs
βββ init.lua
You may register your own handlers to lazy-load plugins via other triggers not already covered by the plugin spec.
You should register all handlers before calling require('lz.n').load
,
because they will not be retroactively applied to
the load
calls that occur before they are registered.
The register_handler
function returns a boolean
that indicates success.
---@param handler lz.n.Handler
---@return boolean success
require("lz.n").register_handler(handler)
lz.n.Handler
Property | Type | Description |
---|---|---|
spec_field | string |
the lz.n.PluginSpec field defined by the handler |
add | fun(plugin: lz.n.Plugin) |
adds a plugin to the handler |
del | fun(plugin: lz.n.Plugin)? |
removes a plugin from the handler |
When writing custom handlers, you can load the plugin and run the hooks from the spec with the following function:
---@type fun(plugins: string | lz.n.Plugin | string[] | lz.n.Plugin[])
require('lz.n').trigger_load
The function accepts plugin names or parsed plugin specs.
It will call the handler's del
function (if it exists) after the before
hooks,
and before load
of the plugin's spec.
All contributions are welcome! See CONTRIBUTING.md.
This library is licensed according to GPL version 2 or (at your option) any later version.