:sloth: lz.n

![LuaRocks][luarocks-shield]

A dead simple lazy-loading Lua library for Neovim plugins.

It is intended to be used

• by users of plugin managers that don't provide a convenient API for lazy-loading.
• by plugin managers, to provide a convenient API for lazy-loading.

[!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.

:star2: Features

• API for lazy-loading plugins on:
  • Events (:h autocmd-events)
  • FileType events
  • Key mappings
  • User commands
  • Colorscheme events
• Works with:
  • Neovim's built-in :h packpath (:h packadd)
  • Any plugin manager that supports manually lazy-loading plugins by name
• Configurable in multiple files

:moon: Introduction

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.

:milky_way: Philosophy

lz.n is designed based on the UNIX philosophy: Do one thing well.

:zzz: Comparison with 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.
• The feature set is minimal, to reduce code complexity and simplify the API. For example, the following lazy.nvim features are out of scope:
  • Merging multiple plugin specs for a single plugin (primarily intended for use by Neovim distributions).
  • 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.
  • Automatic lazy-loading of Lua modules on require.
  • Automatic lazy-loading of colorschemes. lz.n provides a colorscheme handler in the plugin spec.
  • Heuristics for determining a main module and automatically calling a setup() function.
  • Heuristics for loading plugins on require. You can use lzn-auto-require for that.
  • Plugin spec fields (like lazy.nvim's dependencies) for influencing the order in which plugins are loaded. See also: Plugin dependencies.
  • Abstractions for plugin configuration with an opts table. lz.n provides simple hooks that you can use to specify when to load configurations.
  • Features related to plugin management.
  • Profiling tools.
  • UI.
• Some configuration options are different.

:pencil: Requirements

• Neovim >= 0.10.0

:wrench: Configuration

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,
}

:books: Usage

require("lz.n").load(plugins)

• plugins: this should be a table or a string
  • table:
  • A list with your Plugin Specs
  • Or a single plugin spec.
  • string: a Lua module name that contains your Plugin Spec. See Structuring Your Plugins

[!TIP]

• You can call load() as you would call lazy.nvim's setup(). Or, you can also use it to register individual plugin specs for lazy loading.

• See also: :h lz.n

[!IMPORTANT]

Since merging configs is out of scope, calling load() with conflicting plugin specs is not supported.

Plugin spec

[^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.

User events

• 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.

Plugin dependencies

This library does not provide a lz.n.PluginSpec field like lazy.nvim's dependencies. The rationale behind this is that you shouldn't need it. Instead, you can utilise the trigger_load function in a before or after hook.

However, we generally do not recommend this approach. Most plugins primarily rely on the Lua libraries of other plugins, which can be added to the :h package.path without any noticeable impact on startup time.

Relying on another plugin's plugin or after/plugin scripts is considered a bug, as Neovim's built-in loading mechanism does not guarantee initialisation order. Requiring users to manually call a setup function is an anti pattern. Forcing users to think about the order in which they load plugins that extend or depend on each other is even worse. We strongly suggest opening an issue or submitting a PR to fix this upstream. However, if you're looking for a temporary workaround, you can use trigger_load in a before or after hook, or bundle the relevant plugin configurations.

[!NOTE]

• This does not work with plugins that rely on after/plugin, such as many nvim-cmp sources, because Neovim's :h packadd does not source after/plugin scripts after startup has completed. We recommend bundling such plugins with their extensions, or sourcing the after scripts manually. In the spirit of the UNIX philosophy, lz.n does not provide any functions for sourcing plugin scripts. For sourcing after/plugin directories manually, you can use rtp.nvim. Here is an example.

• Why not provide a dependencies field for plugins that don't adhere to best practices? Because it's unnecessary. By using the before and after hooks, you gain full control over when to load another plugin, without cluttering the API.

[!TIP]

We recommend care.nvim as a modern alternative to nvim-cmp.

Examples

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,
    },
    {
        "care.nvim",
        -- load care.nvim on InsertEnter
        event = "InsertEnter",
    },
    {
        "dial.nvim",
        -- lazy-load on keys. -- Mode is `n` by default.
        keys = { "<C-a>", { "<C-x>", mode = "n" } },
    },
}

Structuring Your Plugins

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

:electric_plug: API

Custom handlers

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

To manage handler state safely, ensuring trigger_load can be invoked from within a plugin's hooks, it is recommended to use the :h lz.n.handler.state module.

[!TIP]

For some examples, look at

• The built-in handlers
• The Wiki

Lua API

The following Lua functions are part of the public API.

[!WARNING]

If you use internal functions or modules that are not listed here, things may break without a major version bump.

trigger_load

You can manually load a plugin and run its associated hooks using the trigger_load function:

  ---@overload fun(plugin: lz.n.Plugin | lz.n.Plugin[])
  ---@overload fun(plugin_name: string | string[], opts: lz.n.lookup.Opts): string[]
  require('lz.n').trigger_load

The function provides two overloads, each suited for different use cases:

1. Stateless version:
   • Usage: trigger_load(plugin: lz.n.Plugin)
   • Intended for: Use by a lz.n.Handler
   • Description: This version should be used when working with lz.n.Handler instances to maintain referential transparency. Each handler has full authority over its internal state, ensuring it remains isolated and unaffected by external influences[^5], thereby preventing multiple sources of truth.
2. Stateful version:
   • Usage: trigger_load(plugin_name: string | string[], opts?: lz.n.lookup.Opts)
   • Returns: A list of plugin names that were skipped (empty if all plugins were loaded).
   • Intended for: Scenarios where handler state is unknown or inaccessible, such as in before or after hooks.
   • Description: This version allows you to load plugins by name. It searches through the handlers, querying their lookup functions to identify an appropriate plugin, and returns the first match. You can fine-tune the search process by providing a lz.n.lookup.Opts table.

[^5]: Until the handler is instructed to stop tracking a loaded plugin via its del function.

lookup

To lookup a plugin that is pending to be loaded by name, use:

  ---@type fun(name: string, opts: lz.n.lookup.Opts):lz.n.Plugin?
  require('lz.n').lookup

The lookup, as well as trigger_load(string|string[]) can be fine-tuned with a lz.n.lookup.Opts table:

---@class lz.n.lookup.Opts
---
--- The handlers to include in the search (filtered by `spec_field`)
--- In case of multiple filters, the order of the filter list
--- determines the order in which handlers' `lookup` functions are called.
---@field filter string | string[]

:green_heart: Contributing

All contributions are welcome! See CONTRIBUTING.md.

:book: License

This library is licensed according to GPL version 2 or (at your option) any later version.

[luarocks-shield]: https://img.shields.io/luarocks/v/neorocks/lz.n?logo=lua&color=purple&style=for-the-badge