Oh, I assure you, it’s quite based.
— Phoenix Wright, Ace Attorney
If you’re like me, you still like writing code by hand because you think coding is an art form, not just a means to an end in software development. Like any other art form, it calls for the right tools to help us express our skills. My tool of choice is Neovim.
Neovim probably needs no introduction if you hang around the same tech spaces I do. For the rest of this post, I’ll assume you’re familiar with it and roll your own configuration.
The main draw of Neovim, apart from Vim motions, is that it’s highly configurable. Many Neovim users (myself included) hand-roll their own configurations, curating them over the years and taking great pride in them.
Dependency Hell
Unlike other editors such as VS Code, Zed or JetBrains IDEs, Neovim plugins are fetched directly from source rather than from a central repository. This means your editor already depends on multiple other people’s codebases.
Some plugins, such as fzf-lua, depend on system binaries like fzf, while others on ripgrep, and fd. Some, like blink.cmp, include their own compiled binaries. Your configuration may depend on specific versions of these system binaries too. Add LSP servers, formatters, linters, and more, and it becomes difficult to reproduce the same setup across machines. It can also break easily, with no simple way to roll back updates. Nix comes to the rescue.
What Can Nix Do For You
I solved these problems by using Nix flakes and converting my regular Neovim configuration into a flake that can run on any machine with Nix installed. That covers almost every OS on which you’d want to run Neovim, except Windows (unless you use WSL, but that would be cheating…).
I was inspired by Vimjoyer’s “Homeless Dotfiles With Nix Wrappers” video, which I highly recommend. For the impatient, the basic idea is to package all the dependencies and configuration files alongside the program, so it can run as a standalone package anywhere. As a bonus, it won’t conflict with any packages or user configuration already on the machine.
With this setup, I can run my entire Neovim configuration, including all its LSP servers and formatters, on any machine with Nix installed.
Assuming my config flake is hosted somewhere like GitHub, running it is as simple as:
nix run github:kaezrr/nvim
Yes, that’s it! So simple and easy, without messing with packages or configuration.
Ok But What If I Can’t Use Nix
That sucks, and I hope things get better for you… just kidding. One thing that was important to me was preserving the normalcy of my Neovim configuration. I wanted to be able to use it as a regular old config without Nix.
So I set it up that way: if you clone it into .config/nvim, you can use it as a regular Neovim config, manage plugins with vim.pack, and do everything without Nix. If you have Nix available (and you should, by the way), you can also manage everything with Nix.
So How Do You Do It
Okay, first of all, I won’t cover how to configure Neovim or set up Nix. There are better resources for that. Also, why would you want to make a configuration reproducible if you don’t have one, dummy?
We’ll do roughly the same thing Vimjoyer does in the video. Since his method works for any software you want to package this way, we’ll use Gerg-L’s excellent project, mnw, to focus on Neovim. It stands for Minimal Neovim Wrapper and provides a lightweight way to configure Neovim and its dependencies with Nix.
You can check out my Neovim configuration as you follow the guide if you get stuck. It’s also helpful to keep mnw’s documentation open.
Make sure Nix is installed and configured on your system with the following experimental features enabled:
nix.settings.experimental-features = [
"nix-command"
"flakes"
];
To start, move into your Neovim config folder and initialize a Git repository if you don’t already have one.
Set Up the Flake
Initialize a Nix flake:
nix flake init
Add mnw to your flake inputs:
inputs = {
nixpkgs.url = "https://channels.nixos.org/nixpkgs-unstable/nixexprs.tar.zst";
mnw.url = "github:Gerg-L/mnw";
};
Use the mnw.lib.wrap function to make your wrapped Neovim configuration the default package provided by the flake.
packages = eachSystem (pkgs: {
default = mnw.lib.wrap pkgs ./config.nix;
});
The default attribute here identifies the package that will run if you don’t provide a target when running the flake. You can also add other variants, like nightly or other configurations, and run them with a command such as nix run .#nightly.
The config.nix file is where most of the configuration lives. We’ll cover it briefly.
You can add LSP servers and formatters to the default dev shell. (If you don’t know about dev shells, check them out; they’re awesome.) These won’t be packaged with Neovim, but they’re helpful while you’re configuring it. I add Lua tools here. You could add Nix language servers and formatters too, but I didn’t because I have them installed globally.
The dev shell section of my flake looks like this:
# flake.nix
devShells = eachSystem (pkgs: {
default = pkgs.mkShell {
packages = with pkgs; [
lua-language-server
stylua
];
};
});
If you use direnv, these packages will be available automatically whenever you cd into this folder. Otherwise, run nix develop before working on your config.
Check out the full flake file here.
Configure mnw
Now let’s configure config.nix. The entire file is a Nix function:
# config.nix
{ pkgs, lib, ... }:
let
configDir = "/path/to/your/nvim/config";
in
{
# ...
}
configDir needs to point to where this configuration currently lives. Since the configuration files will be packaged alongside the Neovim app, we don’t need to put them in .config/nvim, though you can if you like.
Then we configure mnw with the pure and impure paths of our Neovim config.
# config.nix
plugins.dev.mnw = {
pure = lib.fileset.toSource {
root = ./.;
fileset = lib.fileset.unions [
./lua
./plugin
];
};
impure = configDir;
};
The pure path evaluates to all the files under /lua and /plugin, which are stored in the Nix store alongside the application. The impure path is used for mnw’s devMode, which lets us tinker with the config live without rebuilding the flake over and over. It’s useful for experimentation and can be used like this:
nix run /path/to/flake#default.devMode
Keep the Config Usable Without Nix
Remember how I said I can use my Neovim config as a regular config, without any hint of Nix, and also as a Nix flake? Here’s how:
# config.nix
initLua = ''
vim.g.nix = true
vim.g.flake_path = "${configDir}";
'';
This defines two Vim global options, nix and flake_path. I can use these options inside my regular Lua config to configure things selectively. vim.g.nix will be true only when this config is used as a Nix flake; otherwise, it will be false.
For example, here’s how I use this option to install plugins with vim.pack when I’m not using flakes:
-- init.lua
if not vim.g.nix then
vim.pack.add {
'https://github.com/neovim/nvim-lspconfig',
'https://github.com/nvim-mini/mini.nvim',
-- ...
}
end
The flake_path variable lets me use the config path in an fzf-lua binding that opens my config directory for quick tinkering. Check out my config for more examples.
Add Plugins and System Tools
Finally, add init.lua and all your Neovim plugins to the config.
# config.nix
luaFiles = [ ./init.lua ];
plugins.start = with pkgs.vimPlugins; [
blink-cmp
nvim-lspconfig
# ...
mini-ai
mini-notify
# ...
nvim-treesitter.withAllGrammars
];
Look up your plugins on search.nixos.org. You might be surprised by how many plugins are already available in nixpkgs. If a plugin isn’t there, mnw lets you source it manually. I don’t have any plugins like that, so you’ll need to refer to the mnw documentation for details. You could also take this opportunity to contribute the missing plugin to nixpkgs!
Note that I add grammars for every language supported by nvim-treesitter. This reduces headaches and keeps my config simple, but it takes up more space and means compiling all the grammars the first time you run the flake. If you don’t want that, you can choose specific languages by replacing:
nvim-treesitter.withAllGrammars
with
nvim-treesitter.withPlugins (p: with p; [
nix
lua
# ....
])
Finally, add any other binaries your Neovim config depends on, such as ripgrep and fd:
# config.nix
extraBinPath =
with pkgs;
[
ripgrep
fd
fzf
# ...
]
++ lib.optionals pkgs.stdenv.hostPlatform.isLinux [ # macOS and other platforms don't need these
pkgs.wl-clipboard
pkgs.xclip
];
Conclusion
And that’s it! Check out the full config on my GitHub, and have a look at mnw too. Now you can run nix run to launch your fully customized, batteries-included Neovim package anywhere!
If you use NixOS like me, you can add your Neovim flake to your NixOS configuration and use it as your system editor. This way, Neovim stays independent of your NixOS system while remaining reproducible. And, if things don’t work out, you can still use it as a regular Neovim configuration.