📚 Important Information

1. This is my personal configuration started from Kickstart-nix.nvim, I really liked the design and decided to base my configuration on it, if you are seeing this don't copy from me instead start from scratch, because I deviate a good amount with my own biases.

🚴 Test drive

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

nix run "github:kossLAN/NvimFlake"

⚡ 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
];

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.

🐧 Non-NixOS

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

nix profile install .#nvim

🤖 Design

Directory structure:

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

📂 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.

📂 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.
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.

📝 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. Here is how I usually do it:

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

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

If you want an impure, but faster feedback loop, you can use $XDG_CONFIG_HOME/$NVIM_APPNAME², where $NVIM_APPNAME defaults to nvim if the appName attribute is not set in the mkNeovim function.

---

1. When adding new files, nix flakes won't pick them up unless they have been committed or staged. ↩︎

2. Assuming Linux. Refer to :h initialization for Darwin. ↩︎