karlprieb/neovim-flake

❄️

A dead simple Nix flake template repository
for Neovim

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

🌌 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¹ (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.

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

🚴 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"

📚 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" ]).

⚡ Installation

❄️ 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
];

🐧 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

📂 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

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

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

⚓ 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

📝 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².
• 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.

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³, 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.

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