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.
- Test drive
- Usage
- Installation
- Philosophy
- Design
- Pre-configured plugins
- Syncing updates
- Alternative / similar projects
If you have Nix installed (with flakes enabled), you can test drive this by running:
nix run "github:mrcjkb/kickstart-nix.nvim"
- Click on Use this template to start a repo based on this template. Do not fork it.
- Add/remove plugins to/from the Neovim overlay.
- Add/remove plugin configs to/from the
nvim/plugin
directory. - Modify as you wish (you will probably want to add a color theme, ...). See: Design.
- Add your flake to you NixOS flake inputs.
- 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
];
With Nix installed (flakes enabled), from the repo root:
nix profile install .#nvim
- KISS principle with sane defaults.
- Manage plugins + external dependencies using Nix (managing plugins shouldn't be the responsibility of a plugin).
- Configuration entirely in Lua1 (Vimscript is also possible). This makes it easy to migrate from non-nix dotfiles.
- 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
.
- See
- Use Neovim's built-in LSP client.
Directory structure:
── flake.nix
── nvim # Neovim configs (lua), equivalent to ~/.config/nvim
── nix # Nix 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 innvim/init.lua
or a module that isrequire
d ininit.lua
. - Configurations for plugins that require explicit initialization
(e.g. via a call to a
setup()
function) should go innvim/plugin/<plugin>.lua
ornvim/plugin/plugins.lua
. - See Initialization order for details.
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
This derivation creates an init.lua
as follows:
- Add
nvim/lua
to theruntimepath
. - Add the content of
nvim/init.lua
. - Add
nvim/*
to theruntimepath
. - Add
nvim/after
to theruntimepath
.
This means that modules in nvim/lua
can be require
d 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.
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
.
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 [email protected]:mrcjkb/kickstart-nix.nvim.git
Fetch and merge changes:
git fetch upstream
git merge upstream/main --allow-unrelated-histories
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 that organises plugins into categories. It also separates lua and nix configuration.lazy-nix-helper.nvim
: For lazy.nvim users who would like to manage plugins with Nix, but load them with lazy.nvim.
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).
Footnotes
-
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. ↩