nvim-neorocks / lz.n

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

🦥 lz.n

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.

🌟 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

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

🌌 Philosophy

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

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

📝 Requirements

• Neovim >= 0.10.0

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

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

Plugin spec

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.	name1
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 automatically2.
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.

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

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

paq-nvim example

require "paq" {
    { "nvim-telescope/telescope.nvim", opt = true }
    { "NTBBloodBatch/sweetie.nvim", opt = true }
}

require("lz.n").load {
    {
        "telescope.nvim",
        cmd = "Telescope",
    },
    {
        "sweetie.nvim",
        colorscheme = "sweetie",
    },
}

Nix (Home Manager) example

programs.neovim = {
  enable = true;
  plugins = with pkgs.vimPlugins [
    lz-n
    {
      plugin = pkgs.vimPlugins.telescope-nvim;
      config = ''
        require("lz.n").load {
          "telescope.nvim",
          cmd = "Telescope",
        }
      '';
      type = "lua";
      optional = true;
    }
    {
      plugin = pkgs.vimPlugins.sweetie-nvim;
      config = ''
        require("lz.n").load {
          "sweetie.nvim",
          colorscheme = "sweetie",
        }
      '';
      type = "lua";
      optional = true;
    }
  ];
};

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

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

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

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.

💚 Contributing

All contributions are welcome! See CONTRIBUTING.md.

📖 License

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

Footnotes

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

3. This is equivalent to lazy.nvim's VeryLazy event. ↩

4. It does not merge multiple specs for the same plugin from different files. ↩