:grey_question: Why kickstart-nix.nvim

If Nix and Neovim have one thing in common, it's that many new users don't know where to get started. Most Nix-based Neovim setups assume deep expertise in both realms, abstracting away Neovim's core functionalities as well as the Nix internals used to build a Neovim config. Frameworks and module-based DSLs are opinionated and difficult to diverge from with one's own modifications.

kickstart-nix.nvim is different: It's geared for users of all levels, making the migration of Neovim configurations to Nix straightforward. This project aims to be as simple as possible, while allowing for maximum flexibility.

[!NOTE]

Similar to kickstart.nvim, this repository is meant to be used by you to begin your Nix/Neovim journey; remove the things you don't use and add what you miss.

:milky_way: Philosophy

• KISS principle with sane defaults.
• Manage plugins + external dependencies using Nix (managing plugins shouldn't be the responsibility of a plugin).
• Configuration entirely in Lua[^1] (Vimscript is also possible). This makes it easy to migrate from non-nix dotfiles.
• Use Neovim's built-in loading mechanisms. See:
  • :h initialization
  • :h runtimepath
  • :h packadd
• Use Neovim's built-in LSP client, with Nix managing language servers.

[^1]: The absence of a Nix module DSL for Neovim configuration is deliberate. If you were to copy the nvim directory to $XDG_CONFIG_HOME, and install the plugins, it would work out of the box.

:star2: Features

• Use either nixpkgs or flake inputs as plugin sources.
• Usable on any device with Neovim and Nix installed.
• Create multiple derivations with different sets of plugins, and simple regex filters to exclude config files.
• Uses Nix to generate a .luarc.json in the devShell's shellHook. This sets up lua-language-server to recognize all plugins and the Neovim API.

:bicyclist: Test drive

If you have Nix installed (with flakes enabled), you can test drive this by running:

nix run "github:nix-community/kickstart-nix.nvim"

:books: Usage

1. Click on Use this template to start a repo based on this template. Do not fork it.
2. Add/remove plugins to/from the Neovim overlay.
3. Add/remove plugin configs to/from the nvim/plugin directory.
4. Modify as you wish (you will probably want to add a color theme, ...). See: Design.
5. You can create more than one package using the mkNeovim function by
   • Passing different plugin lists.
   • Adding ignoreConfigRegexes (e.g. = [ "^ftplugin/.*.lua" ]).

[!TIP]

The nix and lua files contain comments explaining what everything does in detail.

:zap: Installation

:snowflake: NixOS (with flakes)

1. Add your flake to your NixOS flake inputs.
2. Add the overlay provided by this flake.

nixpkgs.overlays = [
    # replace <kickstart-nix-nvim> with the name you chose
    <kickstart-nix-nvim>.overlays.default
];

You can then add the overlay's output(s) to the systemPackages:

environment.systemPackages = with pkgs; [
    nvim-pkg # The default package added by the overlay
];

[!IMPORTANT]

This flake uses nixpkgs.wrapNeovimUnstable, which has an unstable signature. If you set nixpkgs.follows = "nixpkgs"; when importing this into your flake.nix, it may break. Especially if your nixpkgs input pins a different branch.

:penguin: Non-NixOS

With Nix installed (flakes enabled), from the repo root:

nix profile install .#nvim

:robot: Design

Directory structure:

── flake.nix
── nvim # Neovim configs (lua), equivalent to ~/.config/nvim
── nix # Nix configs

:open_file_folder: Neovim configs

• Set options in init.lua.
• Source autocommands, user commands, keymaps, and configure plugins in individual files within the plugin directory.
• Filetype-specific scripts (e.g. start LSP clients) in the ftplugin directory.
• Library modules in the lua/user directory.

Directory structure:

── nvim
  ├── ftplugin # Sourced when opening a file type
  │  └── <filetype>.lua
  ├── init.lua # Always sourced
  ├── lua # Shared library modules
  │  └── user
  │     └── <lib>.lua
  ├── plugin # Automatically sourced at startup
  │  ├── autocommands.lua
  │  ├── commands.lua
  │  ├── keymaps.lua
  │  ├── plugins.lua # Plugins that require a `setup` call
  │  └── <plugin-config>.lua # Plugin configurations
  └── after # Empty in this template
     ├── plugin # Sourced at the very end of startup (rarely needed)
     └── ftplugin # Sourced when opening a filetype, after sourcing ftplugin scripts

[!IMPORTANT]

• Configuration variables (e.g. vim.g.<plugin_config>) should go in nvim/init.lua or a module that is required in init.lua.
• Configurations for plugins that require explicit initialization (e.g. via a call to a setup() function) should go in nvim/plugin/<plugin>.lua or nvim/plugin/plugins.lua.
• See Initialization order for details.

:open_file_folder: Nix

You can declare Neovim derivations in nix/neovim-overlay.nix.

There are two ways to add plugins:

• The traditional way, using nixpkgs as the source.
• By adding plugins as flake inputs (if you like living on the bleeding-edge). Plugins added as flake inputs must be built manually.

Directory structure:

── flake.nix
── nix
  ├── mkNeovim.nix # Function for creating the Neovim derivation
  └── neovim-overlay.nix # Overlay that adds Neovim derivation

:mag: Initialization order

This derivation creates an init.lua as follows:

1. Add nvim/lua to the runtimepath.
2. Add the content of nvim/init.lua.
3. Add nvim/* to the runtimepath.
4. Add nvim/after to the runtimepath.

This means that modules in nvim/lua can be required in init.lua and nvim/*/*.lua.

Modules in nvim/plugin/ are sourced automatically, as if they were plugins. Because they are added to the runtime path at the end of the resulting init.lua, Neovim sources them after loading plugins.

:electric_plug: Pre-configured plugins

This configuration comes with a few plugins pre-configured.

You can add or remove plugins by

• Adding/Removing them in the Nix list.
• Adding/Removing the config in nvim/plugin/<plugin>.lua.

:anchor: Syncing updates

If you have used this template and would like to fetch updates that were added later...

Add this template as a remote:

git remote add upstream git@github.com:nix-community/kickstart-nix.nvim.git

Fetch and merge changes:

git fetch upstream
git merge upstream/main --allow-unrelated-histories

:pencil: Editing your config

When your neovim setup is a nix derivation, editing your config demands a different workflow than you are used to without nix. A quick and easy way to test your changes:

• Perform modifications and stage any new files[^2].
• Run nix run /path/to/neovim/#nvim or nix run /path/to/neovim/#nvim -- <nvim-args>

[^2]: When adding new files, nix flakes won't pick them up unless they have been committed or staged.

This requires a rebuild of the nvim derivation, but has the advantage that if anything breaks, it's only broken during your test run.

When developing locally you might want to have a faster feedback loop. Normally the whole Neovim configuration is copied into the store and the wrapper which nix generates for the derivation calls nvim with -u /nix/store/path/to/generated-init.lua. We can deactivate this behavior with wrapRc = false, so that the config is loaded from $XDG_CONFIG_HOME/$NVIM_APPNAME[^3], where $NVIM_APPNAME defaults to nvim if the appName attribute is not set in the mkNeovim function.

The Flake exposes a dev shell with a nvim-dev package. The lua configuration in ./nvim is automatically symlinked to ~/.config/nvim-dev.

After activating the shell with nix develop or nix-direnv you can run Neovim with nvim-dev to automatically reload your lua configuration. All Nix changes still require a rebuild.

[^3]: Assuming Linux. Refer to :h initialization for Darwin.

:link: Alternative / similar projects

• kickstart.nvim: Single-file Neovim configuration template with a similar philosophy to this project. Does not use Nix to manage plugins.
• neovim-flake: Configured using a Nix module DSL.
• NixVim: A module system for Neovim, with a focus on plugin configs.
• nixCats-nvim: A project that organises plugins into categories. It also separates lua and nix configuration.
• lz.n: A plugin-manager agnostic Lua library for lazy-loading plugins. Can be used with Nix.

[!NOTE]

When comparing with projects in the "non-Nix world", this repository would be more comparable to kickstart.nvim (hence the name), while the philosophies of neovim-flake and NixVim are more in line with a Neovim distribution like LunarVim or LazyVim (though they are far more minimal by default).