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. kickstart-nix.nvim is different: It's geared for users of all levels, making the migration of Neovim configurations to Nix straightforward.

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.

Quick Links

• Test drive
• Usage
• Installation
• Philosophy
• Design
• Pre-configured plugins
• Alternative / similar projects

Test drive

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

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

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.

Installation

NixOS (with flakes)

1. Add your flake to you 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
];

Non-NixOS

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

nix profile install .#nvim

Philosophy

• Slightly opinionated 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[^2].
• Usable on any device with Neovim and Nix installed.
• Ability to create multiple derivations with different sets of plugins.
• Use either nixpkgs or flake inputs as plugin source.
• Use Neovim's built-in loading mechanisms.
  • See :h initializaion and :h runtimepath.
• Use Neovim's built-in LSP client.

[^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, it would work out of the box. [^2]: Caveat: after/ directories are not sourced in the Nix derivation.

Design

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

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.

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 in nix/plugin-overlay.nix.

Directory structure:

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

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.

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.

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.

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 Neovim distribution configured using a NixOS module.
• nixCats-nvim: A project with a similar philosophy to this one that organises plugins into categories.

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 more minimal by default).