Migrating to rocks.nvim

Benefits over other package managers

1. rocks.nvim makes dependency management the responsibility of the plugin.

   With other package managers you as a user have to specify the dependencies for the plugin. Using lazy.nvim it might look like this:

   return {
     "NeogitOrg/neogit",
      dependencies = {
        "nvim-lua/plenary.nvim",
        "nvim-telescope/telescope.nvim",
        "sindrets/diffview.nvim",
      },
      opts = opts,
   }
   

   There are several issues with this:

   1. It’s annoying.
   2. You need to babysit the config if the plugin adds or removes a dependency.
   3. The plugin might break if there’s a breaking change in a dependency.
   4. What if you have several plugins that depend on a different version of a dependency? (You’re going to have a bad time.)

   rocks.nvim moves the dependency management to the plugin, so we can just specify the plugin itself:

   "neo-tree.nvim" = "3.26"
   

   This makes plugin management easier and should reduce the risk of plugins breaking.

2. rocks.nvim supports loading Lua packages from luarocks.

   Lua is a neat little language but it’s very bare-bones and doesn’t include a large standard library. Neovim has been incorporating more and more utility functions—such as vim.split and vim.fs.joinpath()—but there are still plenty of functionality that we need to import. That’s why utility plugins such as plenary.nvim exists and is a dependency to a lot of different plugins.

   With luarocks you get access to many more libraries; for example a yaml and a toml library that would’ve saved me from parsing them with regex.

Drawbacks compared to lazy.nvim

Naturally, it’s not all fun and games and there are drawbacks to rocks.nvim compared to lazy.nvim:

1. Most plugins don’t have a rockspec that define their dependencies, meaning you still need to manage the dependencies yourself, forgoing the biggest benefit of rocks.nvim.

2. Installing and updating all packages feels a lot slower.

3. You must manage lazy loading manually. I’ve seen rumors of lazy loading support for rocks.nvim but as I’m writing this post there’s nothing released yet.

4. rocks.nvim is newer than lazy.nvim; meaning less fancy features, more bugs, and more rough edges.

While I think that rocks.nvim is taking a necessary and difficult step forward for Neovim package managers, there are valid reasons to stick with lazy.nvim.

Separate config file per plugin

One feature I really like about lazy.nvim is the ability to separate plugin configuration into separate files. This is easy to setup in rocks.nvim using rocks-config.nvim:

1. Run :Rocks install rocks-config.nvim or edit rocks.toml manually:

   [plugins]
   "rocks-config.nvim" = "1.6.0"
   

2. Create a plugin-specific file at lua/plugins/<plugin-name>.lua with the plugin setup and configuration code.

   For example, we can install conform.nvim with :Rocks install conform.nvim and configure it in lua/plugins/conform.lua:

   require("conform").setup({
     formatters_by_ft = {
       lua = { "stylua" }
     }
   })
   

Something to keep in mind when migrating to a setup with a config file per plugin is a potential ordering issue. I for example use mason-lspconfig.nvim for my LSP setup and it’s important to call the setup in the right order:

1. Setup mason.nvim.
2. Setup mason-lspconfig.nvim.
3. Setup lspconfig.

If the plugins have their own config file then we can’t guarantee this order. We can instead setup them all in one of the config files—although I’m not a fan of commingling setup of different plugins in a single file in lua/plugins, I prefer them to have a 1-to-1 relationship with a plugin. I think it’s cleaner to place such a file in a runtimepath such as plugin/lspconfig.lua.

Git dependencies

Another crucial feature is the ability to install plugins from git repositories. This requires the rocks-git.nvim module that’s installed with :Rocks install rocks-git.nvim:

[plugins]
"rocks-git.nvim" = "1.5.1"

You can then add git dependencies using :Rocks install <git-path> or add them to rocks.toml manually:

[plugins]
"vim-fugitive" = { git = "tpope/vim-fugitive" }
"trouble.nvim" = { git = "folke/trouble.nvim", branch = "dev" }
"nvim-ts-autotag" = { git = "windwp/nvim-ts-autotag", rev = "aeb7090" }

As I’m writing this almost exactly half of my plugins in rocks.toml depends on a git repository instead of luarocks. Mostly because they don’t exist on luarocks but I also have some Vimscript plugins that never will be.

One feature I’m missing is a command to automatically update rev to the latest available value or removing it, now I did it manually.

The problem with lazy loading

Before looking at how to implement lazy loading, I’d like to bring up a few problems with lazy loading plugins.

1. It’s easy to half-ass it.

   For example, with lazy.nvim you can add commands and events that you want to lazy load on:

   {
     "nvim-treesitter/nvim-treesitter",
     cmd = { "TSInstall", "TSUpdate" },
     event = { "BufReadPre", "BufNewFile" },
     config = config,
     build = ":TSUpdate",
   }
   

   But how do you know that you used the correct events and listed the right commands? And how do you keep up to date when a plugin adds or removes commands?

   I managed to get really agitated when I thought I’d messed up the treesitter installation when I couldn’t call :TSInstallInfo, until I remembered that I hadn’t registered that command to load nvim-treesitter…

   

2. Extra complexity.

   Earlier in this post I complained about having to manage the dependencies for the plugins you install. When you lazy load a plugin you also need to specify commands and events you want to use for lazy load.

   And if you really want to commit to lazy loading as many plugins as possible (I did!) you might end up with some pretty horrendous code, like how you’d lazy load oil.nvim:

   {
     "stevearc/oil.nvim",
     dependencies = { "nvim-tree/nvim-web-devicons" },
     opts = opts,
     command = "Oil",
     -- This is how to lazy load oil according to:
     -- https://github.com/folke/lazy.nvim/issues/533
     init = function()
       if vim.fn.argc() == 1 then
         local stat = vim.loop.fs_stat(vim.fn.argv(0))
         if stat and stat.type == "directory" then
           require("lazy").load({ plugins = { "oil.nvim" } })
         end
       end
       if not require("lazy.core.config").plugins["oil.nvim"]._.loaded then
         vim.api.nvim_create_autocmd("BufNew", {
           callback = function()
             if vim.fn.isdirectory(vim.fn.expand("<afile>")) == 1 then
               require("lazy").load({ plugins = { "oil.nvim" } })
               -- Once oil is loaded, we can delete this autocmd
               return true
             end
           end,
         })
       end
     end,
   }
   

In general I think properly lazy loading should be the responsibility of the plugin, not us as users.

With that said, being able to lazy load plugins is a great feature when you need it.

Lazy setup with packadd and setup

On a basic level you can accomplish lazy loading by following these three steps:

1. Mark the plugin with opt = true.

   [plugins]
   neorg = { version = "1.0.0", opt = true }
   

   This will prevent rocks.nvim from sourcing the plugin at startup.

2. Add the plugin with packadd.

   vim.cmd("packadd neorg")
   

3. Setup and configure the plugin as needed.

Steps 2 and 3 should be done on-demand, for example via an autocommand:

vim.api.nvim_create_autocmd({ "BufReadPre", "BufNewFile" }, {
  pattern = "*.norg",
  callback = function()
    vim.cmd("packadd neorg")
    require("neorg").setup()
    return true
  end,
})

Although packadd is neat, according to rocks.nvim it’s only relevant for the plugin’s ftdetect and plugin scripts. I haven’t seen the need to go quite this far to get a snappy experience and right now I don’t use packadd at all. I don’t even have 100 plugins yet, I’m practically running stock Neovim!

Lazy LSP setup

There’s one instance where I’ve made the plugin setup lazy: the LSP config.

It’s important to me that Neovim starts quickly as I have a weird workflow where I start Neovim dozens of times a day. But after migrating my config I noticed that Neovim was feeling slow. I tracked it down to the LSP setup (and in particular setting up elixir-tools.nvim).

My solution was to create an autocommand that sources the LSP config when reading a file:

vim.api.nvim_create_autocmd({ "BufReadPre", "BufNewFile" }, {
  pattern = "*",
  callback = function()
    require("lazy_plugins.lspconfig")
    return true
  end,
})

local mason_lspconfig = require("mason-lspconfig")

mason_lspconfig.setup({
  -- ...
})

require("elixir").setup({
  -- ...
})

mason_lspconfig.setup_handlers({
  -- ...
})

-- And a bunch of other LSP related setup.

I could of course make it more granular and make more plugins lazy but I haven’t bothered since Neovim now starts under 150 ms, which my brain interprets as instant.