Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/nix-community/kickstart-nix.nvim

❄️ A dead simple Nix flake template repository for Neovim derivations [maintainer=@mrcjkb]
https://github.com/nix-community/kickstart-nix.nvim

flakes neovim nix nixos nvim vim

Last synced: 2 months ago
JSON representation

❄️ A dead simple Nix flake template repository for Neovim derivations [maintainer=@mrcjkb]

Lists

README 

        






  

    kickstart-nix.nvim

  

  

  

    

    

    

    

    

    

    

    

    

    

  

  
❄️


  


    

      A dead simple Nix flake template repository

      for Neovim 

    

  





[![Neovim][neovim-shield]][neovim-url]

[![Nix][nix-shield]][nix-url]

[![Lua][lua-shield]][lua-url]



[![GPL2 License][license-shield]][license-url]

[![Issues][issues-shield]][issues-url]



![](https://github.com/nix-community/kickstart-nix.nvim/assets/12857160/84faa268-82de-4401-acf3-efddc26dd58a)



## :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`](https://github.com/nvim-lua/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`](https://neovim.io/doc/user/starting.html#initialization)

    - [`:h runtimepath`](https://neovim.io/doc/user/options.html#'runtimepath')

    - [`:h packadd`](https://neovim.io/doc/user/repeat.html#%3Apackadd)

- 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](https://nixos.wiki/wiki/Flakes) enabled),

you can test drive this by running:



```console

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

```



## :books: Usage



1. Click on [Use this template](https://github.com/nix-community/kickstart-nix.nvim/generate)

to start a repo based on this template. **Do _not_ fork it**.

1. Add/remove plugins to/from the [Neovim overlay](./nix/neovim-overlay.nix).

1. Add/remove plugin configs to/from the `nvim/plugin` directory.

1. Modify as you wish (you will probably want to add a color theme, ...).

   See: [Design](#design).

1. 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 you NixOS flake inputs.

1. Add the overlay provided by this flake.



```nix

nixpkgs.overlays = [

    # replace  with the name you chose

    .overlays.default

];

```



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



```nix

environment.systemPackages = with pkgs; [

    nvim-pkg # The default package added by the overlay

];

```



### :penguin: Non-NixOS



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



```console

nix profile install .#nvim

```



## :robot: Design



Directory structure:



```sh

── 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:



```sh

── nvim

  ├── ftplugin # Sourced when opening a file type

  │  └── .lua

  ├── init.lua # Always sourced

  ├── lua # Shared library modules

  │  └── user

  │     └── .lua

  ├── plugin # Automatically sourced at startup

  │  ├── autocommands.lua

  │  ├── commands.lua

  │  ├── keymaps.lua

  │  ├── plugins.lua # Plugins that require a `setup` call

  │  └── .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.`) should go in `nvim/init.lua`

>   or a module that is `require`d in `init.lua`.

> - Configurations for plugins that require explicit initialization

>   (e.g. via a call to a `setup()` function) should go in `nvim/plugin/.lua`

>   or `nvim/plugin/plugins.lua`.

> - See [Initialization order](#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 in `nix/plugin-overlay.nix`.



Directory structure:



```sh

── 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`.

1. Add the content of `nvim/init.lua`.

1. Add `nvim/*` to the `runtimepath`.

1. Add `nvim/after` to the `runtimepath`.



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.



## :electric_plug: Pre-configured plugins



This configuration comes with [a few plugins pre-configured](./nix/neovim-overlay.nix).



You can add or remove plugins by



- Adding/Removing them in the [Nix list](./nix/neovim-overlay.nix).

- Adding/Removing the config in `nvim/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:



```console

git remote add upstream [email protected]:nix-community/kickstart-nix.nvim.git

```



Fetch and merge changes:



```console

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.

Here is how I usually do it:



- Perform modifications and stage any new files[^2].

- Run `nix run /path/to/neovim/#nvim`

  or `nix run /path/to/neovim/#nvim -- `



[^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.



If you want an impure, but faster feedback loop,

you can use `$XDG_CONFIG_HOME/$NVIM_APPNAME`[^3], where `$NVIM_APPNAME` 

defaults to `nvim` if the `appName` attribute is not set 

in the `mkNeovim` function.



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



This has one caveat: The wrapper which nix generates for the derivation

calls `nvim` with `-u /nix/store/path/to/generated-init.lua`.

So it won't source a local `init.lua` file.

To work around this, you can put scripts in the `plugin` or `after/plugin` directory.



> [!TIP]

>

> If you are starting out, and want to test things without having to

> stage or commit new files for changes to take effect,

> you can remove the `.git` directory and re-initialize it (`git init`)

> when you are done.



## :link: Alternative / similar projects



- [`kickstart.nvim`](https://github.com/nvim-lua/kickstart.nvim):

  Single-file Neovim configuration template with a similar philosophy to this project.

  Does not use Nix to manage plugins.

- [`neovim-flake`](https://github.com/jordanisaacs/neovim-flake):

  Configured using a Nix module DSL.

- [`NixVim`](https://github.com/nix-community/nixvim):

  A module system for Neovim, with a focus on plugin configs.

- [`nixCats-nvim`](https://github.com/BirdeeHub/nixCats-nvim):

  A project that organises plugins into categories.

  It also separates lua and nix configuration.

- [`lazy-nix-helper.nvim`](https://github.com/b-src/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`](https://www.lunarvim.org/)

> or [`LazyVim`](https://www.lazyvim.org/)

> (though they are far more minimal by default).



[neovim-shield]: https://img.shields.io/badge/NeoVim-%2357A143.svg?&style=for-the-badge&logo=neovim&logoColor=white

[neovim-url]: https://neovim.io/

[nix-shield]: https://img.shields.io/badge/nix-0175C2?style=for-the-badge&logo=NixOS&logoColor=white

[nix-url]: https://nixos.org/

[lua-shield]: https://img.shields.io/badge/lua-%232C2D72.svg?style=for-the-badge&logo=lua&logoColor=white

[lua-url]: https://www.lua.org/

[license-shield]: https://img.shields.io/github/license/nix-community/kickstart-nix.nvim.svg?style=for-the-badge

[license-url]: https://github.com/nix-community/kickstart-nix.nvim/blob/master/LICENSE

[issues-shield]: https://img.shields.io/github/issues/nix-community/kickstart-nix.nvim.svg?style=for-the-badge

[issues-url]: https://github.com/nix-community/kickstart-nix.nvim/issues

[license-shield]: https://img.shields.io/github/license/nix-community/kickstart-nix.nvim.svg?style=for-the-badge

[license-url]: https://github.com/nix-community/kickstart-nix.nvim/blob/master/LICENSE