Report Bug · Request Feature · Ask Question

Allow rocks.nvim to help configure your plugins!

rocks-config.nvim extends rocks.nvim with the ability to configure your plugins.

Simply run :Rocks install rocks-config.nvim, and you are good to go!

With this extension, you can add a [config] table to your rocks.toml, for example:

[plugins]
"neorg" = "7.0.0"
"sweetie.nvim" = "1.0.0"

[config]
plugins_dir = "plugins/"
auto_setup = false

The subdirectory (relative to nvim/lua, default: plugins) to search for plugin configs. You can add a lua/plugins/ directory to your nvim config, with a lua script for each plugin.

── nvim
  ├── lua
  │  └── plugins # Your plugin configs go here.
  │     └── neorg.lua
  │     └── sweetie.lua # or sweetie-nvim.lua
  ├── init.lua

Upon startup, for each plugin in the rocks.toml's [plugins] table, this module will search for a matching config module in and load it if one is found.

If you uninstall a plugin, you can leave its config (e.g. in case you would like to reinstall it later), and it will not cause any problems.

Many Neovim plugins require a call to a setup function, which typically takes a configuration table. If none of the configuration options are lua functions, you can add the config to your rocks.toml, and this plugin will automatically call setup with the plugin's options.

For example, the following lua configuration:

-- lua/plugins/lualine.lua
require('lualine').setup {
  options = {
    icons_enabled = true,
    theme = 'auto',
  },
}

...can also be configured via rocks.toml:

# rocks.toml
[plugins.lualine.config]
options = { icons_enabled = true, theme = "auto" }

The config field can also take on the form of a string pointing to a Lua module (if you would like to execute a one-off script in a different location to the global plugins_dir option):

# rocks.toml
[plugins.lualine]
config = "plugins.statusline" # Will execute `.config/nvim/lua/plugins/statusline.lua`

Some plugins that don't work without a setup call, even if you are happy with the default options. rocks-config.nvim provides a hack to work around this with the auto_setup option (disabled by default). If enabled, and no config is found for an installed plugin, this module will attempt to call require('<plugin-name>').setup() for you.

rocks.nvim makes use of Neovim's built-in initialization sequence, and provides a hook that rocks-config.nvim uses to load configs before any plugin scripts are sourced⁴.

If you need to source a plugin's scripts eagerly (for example, to load colorschemes), you can set the plugin's opt = true in rocks.toml, and then load it with vim.cmd.Rocks({"packadd", "<rock-name>"}) ⁵ or require("rocks").packadd("<rock-name")⁶.

Apart from configuration on a per-plugin basis, it's also possible to create collections of plugins (called bundles) and configure them all in one go.

Below is an example that bundles LSP-related plugins together:

[plugins]
"neodev.nvim"= "scm"
nvim-lspconfig = { version = "0.1.7" } 

[plugins.nvim-cmp]
git = "hrsh7th/nvim-cmp" # Use the git version of nvim-cmp for the best experience.

[bundles.lsp] # Create a bundle called `lsp`
items = [
    "neodev.nvim",
    "nvim-lspconfig",
    "nvim-cmp"
]

Now, instead of invoking each individual configuration file for each plugin separately, rocks-config.nvim will instead look for a lua/plugins/lsp.lua file which it will execute. You can then place your setup code for all three plugins in the same file.

Similarly to regular plugins, a config field can be applied to a bundle. This config field can only be a string pointing to an alternative Lua module to execute. Example:

[bundles.lsp] # Create a bundle called `lsp`
items = [
    "neodev.nvim",
    "nvim-lspconfig",
    "nvim-cmp"
]
config = "bundles.language_support"

Instead of looking inside lua/plugins/lsp.lua, rocks-config.nvim will now search for a file in lua/bundles/language_support.lua.

By default, rocks-config.nvim will not load configs for plugins with opt = true. You can either override this behaviour by setting load_opt_plugins = true, or you can load the config for a plugin using the configure(name) function:

require("rocks-config").configure("foo.nvim")
vim.cmd.packadd("foo.nvim")

rocks-config.nvim is licensed under GPLv3.