As we covered in Chapter 5, plugins are managed by the Lazy.nvim plugin manager. It is configured to automatically load any .lua file in your config folder’s lua/plugins directory. Typically, this will be ~/config/nvim/lua/plugins where ~ is your home directory. However, if you use the NVIM_APPNAME environment variable, then it will be ~/.config/$NVIM_APPNAME/lua/plugins.

Lua files in this directory should always return a Lua table. Therefore, they will be structured like this:

This Lua table can contain either a plugin specification or a table containing multiple plugin specifications in their own Lua table. For example, the structure will either be:

for a single plugin specification, or:

Personally, I usually place each plugin in its own file so they are easy to search for when I use the <Space>fc shortcut. However, I do use the multiple plugin format when the existence of one plugin requires me to modify the configuration of another.

Any one plugin can be specified multiple times in your configuration and LazyVim will merge everything together. There are a few cases where this is useful:

The simplest plugin specification is just a table containing a single string with the GitHub username and repo separated by a /. Occasionally, this is all you need, especially for VimScript plugins. If the plugin in question isn’t hosted on GitHub, you can omit this first argument and pass either dir=/path/to/a/folder or url=https://domain.com/path/to/plugin.

If you need to pin your plugin to a specific version or git branch, you can pass the branch, tag, commit, or version. For GitHub-hosted plugins, you can find the values for these version specifiers on GitHub. You will likely use this only rarely, as it is normal to install the main branch of the plugin. But if you know that a recent change in a plugin is causing issues for you, or if you want to try out some bleeding edge feature that hasn’t been merged yet, you’ll want to set one of these.

There are almost two dozen options you can pass to a Lazy.nvim plugin specification, all documented at https://lazy.folke.io/spec. We discussed some of them in Chapter 5, namely enabled, opts, and keys. Now we’ll touch on several of the others.

There are several options that are invoked at various times during the lifecycle of a plugin. You only need to specify these rarely, but they can be very useful to control when code executes, especially if you are trying to port “raw config” installation instructions to Lazy.nvim config.

The “merging” that LazyVim does on opts if you supply a table may not always do the right thing, especially with nested tables or if you want to remove, instead of add, a key. Sometimes it is better to specify opts as a Lua function that takes the existing opts as input and modifies it in place. A great example of this is the LazyVim recipe for adding a nvim-cmp source:

Here, opts is specified as a function that takes two arguments, and we modify the second one, which is the Lua table LazyVim is building to pass into config. In the case of nvim-cmp the LazyVim spec does not override config, so those opts will be passed to the default config which calls require('nvim-cmp).setup(opts).

LazyVim’s plugin abstractions are usually very elegant, but occasionally can get in the way. I wanted to include a complicated example in the hopes it will help you navigate the hairier situations.

The Telescope live_grep integration that ships with LazyVim doesn’t allow us to pass arguments to ripgrep by default. However, there is a telescope-live-grep-args extension that does permit customizing the ripgrep arguments.

Start by visiting the telescope-live-grep-args.nvim repository. You’ll find installation instructions for Lazy.nvim (that’s the plugin manager, NOT the LazyVim distro itself) that, at time of writing look like this:

The reason I added the “not helpful” comment there is the call to config. LazyVim already configures Telescope with a fairly complex function that you can find under the editor section of the plugins menu on the LazyVim website (click the Full spec) tab.

For the most part, LazyVim does a good job of merging its own defaults with any customizations you do with the various plugins it sets up. It’s easy to change or remove keybindings or override the options that get passed into a setup function, for example.

But it’s not easy to override config.

You could do something like this:

This works because the default behaviour of config in Lazy.nvim is to call require(<the_plugin>).setup(opts). So we’re basically copying the contents of that function into our custom function. But if LazyVim happened to have a very complicated config for Telescope, you would have to copy the whole thing in, and it would eventually get out of date with any changes that LazyVim makes in the future. That wouldn’t be fun for you to maintain. More importantly, it runs a very real risk of clobbering any Telescope-related changes that LazyVim makes with other plugins or extras.

In general, I try very hard to avoid implementing config when overriding LazyVim’s defaults. It’s fine to have a custom implementation of config if I am adding a new plugin that LazyVim isn’t aware of, since I’m already responsible for maintaining it. But when I’m customizing plugins, I try not to override config.

The secret (in this case) is to use the “dependencies” feature of Lazy.nvim. The “Full Spec” on the LazyVim website has an example of how to set up the telescope-fzf-native.nvim extension, which looks something like this

This is showing us how to have a mini-config for a dependent plugin, which is exactly what we want. Further, if we customize our spec, dependencies is one of the tables that Lazy.nvim will merge with the parent spec (the one created by LazyVim). So we don’t need to copy the above code into our Telescope extension file so it doesn’t get clobbered. Instead we only need to create a single new table.

Here’s the configuration (I put it in extend-telescope.lua):

It’s kind of verbose, but this should be all you need to enable the plugin.

Next, you need to set up a keybinding to invoke the plugin. You can choose to override the existing <Space>/ keybinding, or perhaps you would use <Space>? if you want to have separate “default live_grep” and “live_grep_args” mode.

Your first attempt, if you are following the live-grep-args README might look like this:

Unfortunately, this is too easy for LazyVim. Because the live_grep_args plugin has been set up to run in a LazyVim.on_load, it is not defined at the time this keys array is created.

The solution is to wrap the call in another function, so the import only happens after you press the keybinding. That works because the onLoad handler will have been called by that point:

Before we move on to actually using the live-grep-args plugin, there is one more place you need to apply this weird nested function calls trick. Telescope-live-grep-args suggests hooking up ctrl-k to the quote_prompt() action, like so:

The table passed into setup there just comes from our opts array, but we again need to avoid importing telescope-live-grep-args at the top-level like that. Instead, we need a new function. But there are a couple gotchas:

The resulting opts array looks like this:

For completeness (and because all the above snippets on their own may not make indentational sense), here is my entire Telescope configuration:

It’s a mess, I know. Part of the mess is because Telescope is pretty generic, and that mess would still exist if you were managing your own config. But part of the mess is because we need to cooperate with LazyVim when we enter our customizations, and the config is necessarily more complicated than it would be. As usual, I’m ok with this because I have to do it rarely enough and I appreciate not having to manage most of my configuration by myself.

Vim is a highly configurable editor and Neovim is even more so. There are over three hundred options in the :help option-list output. The default Vim configuration for most of these is fine, though there are a few that have silly defaults for historical reasons. Neovim has fixed a few of these and LazyVim sets almost a third of them so the out-of-the-box experience approximates what most modern developers would want.

However, you’ll probably still want to change a few options to suit your taste. This is typically done in the lua/config/options.lua file. LazyVim loads this file by default.

For any given option, you probably want to set the vim.opt.<optionname> field. vim.opt is a special Lua table that allows you to interact with Vim settings as…​ well, a special Lua table. If you are searching for a Vim setting and see something saying you should call :set option=value, that will work, if you want to do it temporarily. But if you want to store the setting for the next time you start Neovim, you need to translate it to vim.opt.option = value.

Sometimes, and after 25 years using Vim I’m still not sure exactly when, you’ll need to set vim.g.<optionname> = value instead. The g in this case means global. If you see an instruction to set a variable such as let g:varname = value, you may need to use vim.g.varname = value. Some options are inherently global while others only apply to the current buffer unless you specify g. Some plugins, especially older non-Lua plugins, are configured with global variables, and this is the syntax you would use for them as well.

In general, use vim.opt unless you see vim.g or g: in the documentation or code you are copying from.

Vim has two options for setting the colour scheme and they can interact in unexpected ways.

First, you can set your window background to be either dark or light. You can toggle this setting at runtime with the <Space>ub keybinding under the “Ui” menu. Usually when you toggle the background, the colour scheme will change the foreground colours to suit the chosen background, but this isn’t always reliable. Sometimes it even changes the colour scheme to a related one that is more suitable when the background is light. For example, if you have catpuccin-mocha enabled, and change your background to light, catpuccin-latte will become the selected colour scheme.

If you want to change the background permanently, set vim.opt.background = "light" or vim.opt.background = "dark" in your options.lua file.

To change to a different colour scheme altogether, use <Space>uC where the C is capitalized. This will pop up a Telescope picker with all currently installed colour schemes. Neovim ships with a few default colour schemes, and LazyVim adds several variations of Catpuccin and Tokyo Night (the default). The advantage of these colour schemes over the Neovim-provided ones is that they have a ton of extra highlight groups for the various plugins LazyVim installs.

If you want to change the colour scheme permanently, it should be set as an opt on the LazyVim/LazyVim plugin. I prefer the catpuccin colour scheme, so I have a plugins/core.lua file that looks like this:

However if you want to set the colour scheme to something that isn’t shipped with LazyVim by default, you also need to install the plugin that ships that colour scheme. For example, the popular standby gruvbox can be installed like this:

LazyVim automatically lazy-load plugins on demand instead of during program startup. This can shave milliseconds off your startup time (that oh-so-precious resource).

LazyVim knows to load the plugin whenever its code is required, or when any of the keybindings specified in the keys array are pressed. This is usually exactly when you want it to load. However, if you encounter plugins that are not working as expected, you may need to tweak the lazy loading configuration.

First, try adding lazy = false to the plugin spec. This will ensure the plugin loads on startup. If the plugin works after you add that, you have two options:

For the most part, I recommend the first option. Micro-optimization makes sense in the context of optimizing plugins for public consumption. Plugin maintainers might use it in their packages, and certainly distro maintainers such as Folke himself spend a lot of time on it. But it’s not likely worth it for you.

Run the plugin with lazy enabled and disabled and check the startup time in the dashboard. If it makes a difference that you want to solve for, read on.

If a plugin should only be specified for certain filetypes, then add a ft key to the spec. This key accepts a string or list of strings representing the filetype. (To get the filetype for the current buffer, type :set ft<Enter>).

If instead the plugin should only be loaded if certain commands are called, specify a list of strings with the command names under the cmd key.

You can also specify a Neovim event that should trigger the plugin to load. There are way too many of these to list in this book, so I’ll refer you to :help events. The most common ones to trigger plugin loading would be BufEnter, BufRead, and BufWrite.

If you need to configure something to run for a specific filetype, you’ll need the nvim_create_autocmd function. Technically you can place this call anywhere, including init.lua or the config or init for a specific plugin, but the LazyVim convention is to put them in the lua/config/autocmds.lua file.

I actually only have one autocmd because LazyVim does such a good job of configuring filetype-specific behaviours for me (usually using the appropriate lang.* LazyVim Extra). That command looks like so:

The first argument is a keyless Lua table of string event names; in this case any time I create or read a file, the autocommand is run. There are other events you can use, but for the most part you’ll only need these two unless you are writing your own plugin (see :help autocmd-events for a whole list).

The second argument contains the options for the autocommand. In this case I am including a pattern, which is a Vim regex for the type of file I want to match. I specifically said “Vim regex” to excuse the goofy \*, as discussed in Chapter 12.

In this case I’m using the command key to execute a command whenever I read a *.svx file. You can instead specify a callback key where the value is a Lua function that will be called whenever the event occurs.

Sometimes, you’ll want to have a custom LazyVim configuration for a specific project. For example, most of my Typescript projects are in Svelte, which means I can’t (yet) use the exceptional biome linter/formatter for them. That means I’m using prettier for formatting in these repos. My extend-conform.lua plugin specification looks like this:

However, for my Typescript API servers, I can use Biome, and I want to override my configuration for those projects only.

LazyVim makes this dead simple: just create a .lazy.lua file in your project. It can return any valid plugin spec, and it will be called after any other plugins are loaded, overwriting them. So my Hono api server has a .lazy.lua file that looks like this:

You can choose to commit this with your project or .gitignore it depending on the standards of the project.

LazyVim helpfully collects some of the most commonly requested features as recipes on their home page. Most of these can simply be copied directly into any file in your lua/plugins folder. Remember to add return in front of them so that whatever table they give you is exported.

Most of the recipes are just providing a set of suggested opts to trigger the behaviour in question. These opts are always plugin-specific and you’ll need to visit the help file or README for the plugin to understand what they are doing.

This chapter was all about configuring LazyVim. Much of it may have been review of examples I’ve used throughout the book when adding plugins to support specific features. However, I wanted to make sure there was coverage in one place for when you want to look things up.