[Feature] Lazy loading

[GaetanLepage]

-->Summary: https://notes.glepage.com/rA_fyfKESvC9OxGGNHOYXw#Lazy-Loading <--

Currently, nixvim relies on the neovim built-in way of loading plugins.
This is implemented by nixpkgs neovim's module. It has the advantage of existing and leveraging the collection of plugins packaged in nixpkgs.

With that said, the very popular lazy.nvim plugin manager proposes a more performant way of loading plugins.
Imitating their lazy loading process could be a very valuable addition to nixvim.
I would guess that this feature should be optional so that conventional loading would stay the default.

As of today, no-one has started to work on this issue.
Feel free to go and make a PR, even if the work is in draft-stage. I will personally be glad to review and discuss a proposed implementation.

[pta2002]

A (relatively) easy way to do this, compared to lazy.nvim's approach of basically redoing the whole lazy-loading machinery in neovim, is to make use of optional plugin loading - this is supported, I don't really remember how, but it's a matter of checking how wrapNeovim works.

This way, we can :packadd the packages only when they're needed - AFAIK this is basically how plugin lazy-loading has been done in the past.

Second, probably easier, option - the vast majority of the plugins we support are lua-based plugins. The majority of the loading time there is spent on the setup function. What if we just avoid calling that function until it's needed?

Either way, I will be looking into how lazy-loading in neovim has been traditionally done, since I don't have much experience with it, and will try to come up with some way it could work.

[pta2002]

Also, another feature lazy.nvim supports is bytecode pre-compilation. This is actually totally something we could do! Basically just need to wrap the plugin's derivations to add that. Something to look into, but I'd say this is better off as a separate feature.

[pta2002]

Some references:

• Examples of lazyloading (Neovim discourse) - Basically, create some convenience functions for delaying lazy-loading, and then bind them that way. We have all the machinery required right now - we can create autocommands, rebind commands and rebind keys. With this, we can just shim a plugin's commands and :packadd the plugin when they're called, or wait for an autocommand to load them.

[GaetanLepage]

Either way, I will be looking into how lazy-loading in neovim has been traditionally done, since I don't have much experience with it, and will try to come up with some way it could work.

Great ! Thanks and good luck :)
Feel free to open a PR as soon as you have a draft so that I can help and provide feedback :)

[stasjok]

Yesterday I found out about nixvim. I'm already using home-manager. I'm not sure I would migrate though. I do some customization for neovim loading to greatly improve startup time and I'm not sure I can insert nixvim in that process. But the project looks interesting. Still I wanted to comment about lazy loading. What I think is most important for startup time are:

1. Reducing vim.api.nvim_list_runtime_paths(). It's an actual search path where neovim will look for files. More plugins, longer the list. What is even worse in nix ecosystem is that every tree-sitter parser is actually a separate plugin. So when you are installing all parsers, your list_runtime_paths contains hundreds of entries. It's very bad for startup time. Just merging all parsers to a single plugin with symlinkJoin can greatly reduce startup time. But I went even further. I merged all plugins into one plugin pack with buildEnv. So my list_runtime_paths contains only 6 entries (.config/nvim, vim-pack-dir, vim-pack-dir/pack/myNeovimPackages/start/plugin-pack, nvim/runtime, vim-pack-dir/pack/myNeovimPackages/start/plugin-pack/after, .config/nvim/after).
   vim.loader can alleviate a long search path, because it caches directories, so nvim will not search in very directory. But vim.loader is only for lua files. Neovim also scan all directories for plugins, ftplugins, syntax and so on. So reducing list_runtime_paths improves things every time you load a buffer (because of autocommands scanning for ftplugin, syntax, indent).
   Overall reducing vim.api.nvim_list_runtime_paths() gave me the biggest impact. But unfortunately it's not an universal solution, because of file collisions. I'm currently removing help tags in every plugin and generating a new one for the entire pack. Also I'm limiting linked directories with pathsToLink.

2. Byte-compiling every lua file. With nix we have a build step, so it's better to do a compilation beforehand, and not cache during startup. I compile every lua file: every file in every plugin, every file in my .conf/nvim directory, init.lua, and nvim runtime directory. I have a build hook that does that. As a result I have a fast startup time even on first startup and I don't pollute .cache/nvim with thousands of compiled lua files (with nix every new configuration has different path, so there are a lot of old files there). I don't use vim.loader at all. With both 1 and 2 I have even faster startup time than vim.loader. There is one caveat: lua-language-server can't parse compiled files. As a workaround I save a list of directories with original files in json and load it to lua_ls config.

3. Reduce a number of required lua files. Usually it means not using heavy functions as callbacks for mappings. I mean do something like callback = function() require("plugin.functions").do_something() end. But you don't need to do it if require("plugin").setup() already pulling all relevant files, you won't improve speed in that case, rather the opposite (every time you use that binding).

4. I don't do it personally, but it's possible to defer plugin setup on some event (like mapping or command). packadd will increase vim.api.nvim_list_runtime_paths() for my case, so I never use optional plugins.

So even not doing any lazy-loading I have a decent startup time. Without all these optimizations vim.loader greatly improves things. But 1) improves it even further. Maybe some of it can be implemented in nixvim. For example merging treesitter parsers in one plugin (minus 200 to vim.api.nvim_list_runtime_paths()) and byte-compiling init.lua (vim.loader doesn't compile it, because it's enabled after).

[GaetanLepage]

Thank you so much @stasjok for this great insight of your config !
This will surely help once we will tackle the performance issue seriously.

[koalagang]

I'm not using nixvim either because I need the lazy-loading but I'd like to chip in an idea. If you're willing to outsource some of the code, I'd suggest using lazy.nvim seeing as it's pretty good at lazy-loading + it would reduce the maintenance burden for developing nixvim. Its variety of options and features could come in handy. It even has async execution and automatic caching and bytecode compilation of Lua modules for improved performance. You could provide options to configure it in nix and then translate that to lua like you do with the rest of nixvim. Lazy's dir option could be used to specify the path to the plugin in the nix store. For plugins not available in the nix repos, you could generate packages (see how they do it in the nix repos) or even just let lazy.nvim handle it internally (using git) if you don't mind installing stuff outside of the nix store.

I've written some examples below to illustrate the idea.
The nix file:

{
  plugins.lazy = {
    enable = true;

    # install any plugin available in the nix repos
    nix = {

      # this installs vimPlugins.neorg
      neorg = {
        build = ":Neorg sync-parsers";
        dependencies = [
          # these are all from the nix repos too
          # they load when Neorg loads
          plenary-nvim
          nvim-treesitter
          neorg-telescope = {
            dependencies = [ telescope-nvim ];
            config = ''
              -- this is lua code
              -- it does not get loaded until neorg-telescope is loaded
              vim.wo.foldlevel = 99
            '';
          };
        ];
        cmd = "Neorg";
        ft = "norg";
        keys = "<c-t>n";
        # sometimes we like to keep the config in a different file
        # so source it from elsewhere
        config = import ./neorg.nix;
      };

      nvim-colorizer-lua = {
        cmd = "ColorizerToggle"; # only load colorizer when I use :ColorizerToggle
        config = ''
          -- more lua code
          vim.g.termguicolors = true,
          require("colorizer").setup()
        '';
      };
    };

    # obscure plugin that isn't available in the nix repos
    git."Vonr/align.nvim" = {
        branch = "v2";
        # only load align.nvim when the user presses <leader>a in visual mode
        keys = [
          { "<leader>a"; mode = "v"; };
        ];
        config = ''
          vim.keymap.set(
              'v',
              '<leader>a',
              function()
                  require'align'.align_to_string({
                      preview = true,
                  })
              end,
              { noremap = true, silent = true }
          )
        '';
      };
  };
}

This would install pkgs.vimPlugins.lazy-nvim, pkgs.vimPlugins.neorg, pkgs.vimPlugins.nvim-colorizer-lua, pkgs.vimPlugins.plenary-nvim, pkgs.vimPlugins.nvim-treesitter, pkgs.vimPlugins.neorg-telescope and pkgs.vimPlugins.telescope-nvim.
It would also generate a lua file that looks something like this:

-- add lazy.nvim to the runtime path
vim.opt.rtp:prepend("/nix/store/rjkwbzdmdfp9gfrvi0rch5g5illqwbgf-vimplugin-lazy.nvim-2023-08-26")

require("lazy").setup({
  {
      name = "neorg",
      dir = "/nix/store/iwxg2w4blbphyk7yvf7drqkmf8qfyv4x-vimplugin-neorg-2023-09-15",
      build = ":Neorg sync-parsers",
      dependencies = {
          { name = "plenary.nvim", dir = "/nix/store/4f17ss3v7lv580hmca8pc2q3zn33lqk4-lua5.1-plenary.nvim-2023-09-12" },
          { name = "nvim-treesitter", dir = "/nix/store/vp0lhrdzvknz7rb8pc6ndvv28cgsfy14-vimplugin-nvim-treesitter-2023-09-16" },
          {
              name = "telescope.nvim",
              dir = "/nix/store/1ldgn56d6sgmk42n6dna3b91w3si3sn7-lua5.1-telescope.nvim-2023-09-16",
              dependencies = { name = "neorg-telescope", dir = "/nix/store/rvg763iaqbx3czb52ghrsxhidvqqgwbk-vimplugin-neorg-telescope-2023-08-06" },
              config = function()
                -- this is lua code
                -- it does not get loaded until neorg-telescope is loaded
                vim.wo.foldlevel = 99
              end,
          },
      },
      cmd = "Neorg",
      ft = "norg",
      keys = "<c-t>n",
      config = function()
        require("path.to.neorg.config")
      end,
  },

  {
      name = "nvim-colorizer.lua",
      dir = "/nix/store/03k72h7x4m543z7vrqjwbvqjx6j789qg-vimplugin-nvim-colorizer.lua-2023-02-27",
      cmd = "ColorizerToggle",
      config = function()
        -- more lua code
        vim.g.termguicolors = true,
        require("colorizer").setup()
      end,
  },

  {
    "Vonr/align.nvim",
    branch = "v2",
    keys = {{ "<leader>a", mode = "v" }},
    config = function()
        vim.keymap.set(
            'v',
            '<leader>a',
            function()
                require'align'.align_to_string({
                    preview = true,
                })
            end,
            { noremap = true, silent = true }
        )
    end,
  },
})

Note that you shouldn't try to lazy-load lazy.nvim or the colourscheme. These should be loaded on startup.
As a related sidenote, you can install stuff with lazy.nvim without lazy-loading them by using the lazy = false option. If you choose to load the colourscheme plugin using lazy, it's also good practise to use priority = 1000 to make sure it loads before all other plugins.

Cut me some slack if any of the nix or lua code above has mistakes. I'm pretty new to both languages and have so far not used them for anything besides configuring NixOS/home-manager and Neovim.

[koalagang]

Oh btw, I came across another project called nixneovim, which seems to have pretty much the same goal as you. I don't believe they do lazy-loading but maybe some of their stuff would interest you, such as their auto-updated plugins repo.

[GaetanLepage]

Thanks for the link @koalagang !
I knew that this project existed (it was forked from nixvim a while ago). However, I wasn't aware that they had their own repo.
We used to have an infrastructure to package plugins ourselves within nixvim but we have removed it at some point.
Indeed, we now prefer the approach of upstreaming all missing plugins to nixpkgs. This makes the user experience a smoother.
The only downside is that the users of the stable branch might not get the new/updated plugins. I am not aware of any backporting of the plugins by nixpkgs maintainers... (@teto am I right here ?).
Anyway, we don't backport our updates to the nixvim stable branch.