{"id":23035147,"url":"https://github.com/rayslash/nvim","last_synced_at":"2025-04-02T22:22:58.872Z","repository":{"id":245253726,"uuid":"817671143","full_name":"RaySlash/nvim","owner":"RaySlash","description":null,"archived":false,"fork":false,"pushed_at":"2024-07-01T09:57:42.000Z","size":48,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-15T16:48:53.845Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RaySlash.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"mrcjkb","open_collective":"nix-community"}},"created_at":"2024-06-20T07:52:52.000Z","updated_at":"2024-07-01T09:57:45.000Z","dependencies_parsed_at":"2024-06-20T23:25:38.595Z","dependency_job_id":"b2e44da8-4591-4e3c-a834-1eef847962b5","html_url":"https://github.com/RaySlash/nvim","commit_stats":null,"previous_names":["rayslash/nvim"],"tags_count":0,"template":false,"template_full_name":"nix-community/kickstart-nix.nvim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RaySlash%2Fnvim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RaySlash%2Fnvim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RaySlash%2Fnvim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RaySlash%2Fnvim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RaySlash","download_url":"https://codeload.github.com/RaySlash/nvim/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237808183,"owners_count":19369602,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-15T16:38:45.620Z","updated_at":"2025-02-08T12:43:31.256Z","avatar_url":"https://github.com/RaySlash.png","language":"Lua","funding_links":["https://github.com/sponsors/mrcjkb","https://opencollective.com/nix-community"],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable --\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/nix-community/kickstart-nix.nvim\"\u003e\n    \u003cimg src=\"./nvim-nix.svg\" alt=\"kickstart-nix.nvim\"\u003e\n  \u003c/a\u003e\n  \u003c!-- TODO: --\u003e\n  \u003c!-- \u003cp align=\"center\"\u003e --\u003e\n    \u003c!-- \u003cbr /\u003e --\u003e\n    \u003c!-- TODO: --\u003e\n    \u003c!-- \u003ca href=\"./nvim/doc/kickstart-nix.txt\"\u003e\u003cstrong\u003eExplore the docs »\u003c/strong\u003e\u003c/a\u003e --\u003e\n    \u003c!-- \u003cbr /\u003e --\u003e\n    \u003c!-- \u003cbr /\u003e --\u003e\n    \u003c!-- \u003ca href=\"https://github.com/nix-community/kickstart-nix.nvim/issues/new?assignees=\u0026labels=bug\u0026projects=\u0026template=bug_report.yml\"\u003eReport Bug\u003c/a\u003e --\u003e\n    \u003c!-- · --\u003e\n    \u003c!-- \u003ca href=\"https://github.com/nix-community/kickstart-nix.nvim/issues/new?assignees=\u0026labels=enhancement\u0026projects=\u0026template=feature_request.yml\"\u003eRequest Feature\u003c/a\u003e --\u003e\n    \u003c!-- · --\u003e\n    \u003c!-- \u003ca href=\"https://github.com/nix-community/kickstart-nix.nvim/discussions/new?category=q-a\"\u003eAsk Question\u003c/a\u003e --\u003e\n  \u003c!-- \u003c/p\u003e --\u003e\n  \u003cp\u003e❄️\u003c/p\u003e\n  \u003cp\u003e\n    \u003cstrong\u003e\n      A dead simple \u003ca href=\"https://nixos.org/\"\u003eNix\u003c/a\u003e flake template repository\u003c/br\u003e\n      for \u003ca href=\"https://neovim.io/\"\u003eNeovim\u003c/a\u003e \n    \u003c/strong\u003e\n  \u003c/p\u003e\n\n[![Neovim][neovim-shield]][neovim-url]\n[![Nix][nix-shield]][nix-url]\n[![Lua][lua-shield]][lua-url]\n\n[![GPL2 License][license-shield]][license-url]\n[![Issues][issues-shield]][issues-url]\n\u003c/div\u003e\n\u003c!-- markdownlint-restore --\u003e\n\n![](https://github.com/nix-community/kickstart-nix.nvim/assets/12857160/84faa268-82de-4401-acf3-efddc26dd58a)\n\n## :grey_question: Why kickstart-nix.nvim\n\nIf Nix and Neovim have one thing in common,\nit's that many new users don't know where to get started.\nMost Nix-based Neovim setups assume deep expertise in both realms,\nabstracting away Neovim's core functionalities\nas well as the Nix internals used to build a Neovim config. \nFrameworks and module-based DSLs are opinionated and difficult to diverge from\nwith one's own modifications.\n\n`kickstart-nix.nvim` is different: \nIt's geared for users of all levels,\nmaking the migration of Neovim configurations to Nix straightforward.\nThis project aims to be as simple as possible, while allowing\nfor maximum flexibility.\n\n\u003e [!NOTE]\n\u003e\n\u003e Similar to [`kickstart.nvim`](https://github.com/nvim-lua/kickstart.nvim),\n\u003e this repository is meant to be used by **you** to begin your\n\u003e **Nix**/Neovim journey; remove the things you don't use and add what you miss.\n\n## :milky_way: Philosophy\n\n- KISS principle with sane defaults.\n- Manage plugins + external dependencies using Nix\n  (managing plugins shouldn't be the responsibility of a plugin).\n- Configuration entirely in Lua[^1] (Vimscript is also possible).\n  This makes it easy to migrate from non-nix dotfiles.\n- Use Neovim's built-in loading mechanisms. See:\n    - [`:h initialization`](https://neovim.io/doc/user/starting.html#initialization)\n    - [`:h runtimepath`](https://neovim.io/doc/user/options.html#'runtimepath')\n    - [`:h packadd`](https://neovim.io/doc/user/repeat.html#%3Apackadd)\n- Use Neovim's built-in LSP client, with Nix managing language servers.\n\n[^1]: The absence of a Nix module DSL for Neovim configuration is deliberate.\n      If you were to copy the `nvim` directory to `$XDG_CONFIG_HOME`,\n      and install the plugins, it would work out of the box.\n\n## :star2: Features\n\n- Use either nixpkgs or flake inputs as plugin sources.\n- Usable on any device with Neovim and Nix installed.\n- Create multiple derivations with different sets of plugins,\n  and simple regex filters to exclude config files.\n- Uses Nix to generate a `.luarc.json` in the devShell's `shellHook`.\n  This sets up lua-language-server to recognize all plugins\n  and the Neovim API.\n\n## :bicyclist: Test drive\n\nIf you have Nix installed (with [flakes](https://wiki.nixos.org/wiki/Flakes) enabled),\nyou can test drive this by running:\n\n```console\nnix run \"github:nix-community/kickstart-nix.nvim\"\n```\n\n## :books: Usage\n\n1. Click on [Use this template](https://github.com/nix-community/kickstart-nix.nvim/generate)\nto start a repo based on this template. **Do _not_ fork it**.\n1. Add/remove plugins to/from the [Neovim overlay](./nix/neovim-overlay.nix).\n1. Add/remove plugin configs to/from the `nvim/plugin` directory.\n1. Modify as you wish (you will probably want to add a color theme, ...).\n   See: [Design](#design).\n1. You can create more than one package using the `mkNeovim` function by\n    - Passing different plugin lists.\n    - Adding `ignoreConfigRegexes` (e.g. `= [ \"^ftplugin/.*.lua\" ]`).\n\n\u003e [!TIP]\n\u003e\n\u003e The nix and lua files contain comments explaining\n\u003e what everything does in detail.\n\n## :zap: Installation\n\n### :snowflake: NixOS (with flakes)\n\n1. Add your flake to you NixOS flake inputs.\n1. Add the overlay provided by this flake.\n\n```nix\nnixpkgs.overlays = [\n    # replace \u003ckickstart-nix-nvim\u003e with the name you chose\n    \u003ckickstart-nix-nvim\u003e.overlays.default\n];\n```\n\nYou can then add the overlay's output(s) to the `systemPackages`:\n\n```nix\nenvironment.systemPackages = with pkgs; [\n    nvim-pkg # The default package added by the overlay\n];\n```\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e This flake uses `nixpkgs.wrapNeovimUnstable`, which has an\n\u003e unstable signature. If you set `nixpkgs.follows = \"nixpkgs\";`\n\u003e when importing this into your flake.nix, it may break.\n\u003e Especially if your nixpkgs input pins a different branch.\n\n### :penguin: Non-NixOS\n\nWith Nix installed (flakes enabled), from the repo root:\n\n```console\nnix profile install .#nvim\n```\n\n## :robot: Design\n\nDirectory structure:\n\n```sh\n── flake.nix\n── nvim # Neovim configs (lua), equivalent to ~/.config/nvim\n── nix # Nix configs\n```\n\n### :open_file_folder: Neovim configs\n\n- Set options in `init.lua`.\n- Source autocommands, user commands, keymaps,\n  and configure plugins in individual files within the `plugin` directory.\n- Filetype-specific scripts (e.g. start LSP clients) in the `ftplugin` directory.\n- Library modules in the `lua/user` directory.\n\nDirectory structure:\n\n```sh\n── nvim\n  ├── ftplugin # Sourced when opening a file type\n  │  └── \u003cfiletype\u003e.lua\n  ├── init.lua # Always sourced\n  ├── lua # Shared library modules\n  │  └── user\n  │     └── \u003clib\u003e.lua\n  ├── plugin # Automatically sourced at startup\n  │  ├── autocommands.lua\n  │  ├── commands.lua\n  │  ├── keymaps.lua\n  │  ├── plugins.lua # Plugins that require a `setup` call\n  │  └── \u003cplugin-config\u003e.lua # Plugin configurations\n  └── after # Empty in this template\n     ├── plugin # Sourced at the very end of startup (rarely needed)\n     └── ftplugin # Sourced when opening a filetype, after sourcing ftplugin scripts\n```\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e - Configuration variables (e.g. `vim.g.\u003cplugin_config\u003e`) should go in `nvim/init.lua`\n\u003e   or a module that is `require`d in `init.lua`.\n\u003e - Configurations for plugins that require explicit initialization\n\u003e   (e.g. via a call to a `setup()` function) should go in `nvim/plugin/\u003cplugin\u003e.lua`\n\u003e   or `nvim/plugin/plugins.lua`.\n\u003e - See [Initialization order](#initialization-order) for details.\n\n### :open_file_folder: Nix\n\nYou can declare Neovim derivations in `nix/neovim-overlay.nix`.\n\nThere are two ways to add plugins:\n\n- The traditional way, using `nixpkgs` as the source.\n- By adding plugins as flake inputs (if you like living on the bleeding-edge).\n  Plugins added as flake inputs must be built in `nix/plugin-overlay.nix`.\n\nDirectory structure:\n\n```sh\n── flake.nix\n── nix\n  ├── mkNeovim.nix # Function for creating the Neovim derivation\n  └── neovim-overlay.nix # Overlay that adds Neovim derivation\n```\n\n### :mag: Initialization order\n\nThis derivation creates an `init.lua` as follows:\n\n1. Add `nvim/lua` to the `runtimepath`.\n1. Add the content of `nvim/init.lua`.\n1. Add `nvim/*` to the `runtimepath`.\n1. Add `nvim/after` to the `runtimepath`.\n\nThis means that modules in `nvim/lua` can be `require`d in `init.lua` and `nvim/*/*.lua`.\n\nModules in `nvim/plugin/` are sourced automatically, as if they were plugins.\nBecause they are added to the runtime path at the end of the resulting `init.lua`,\nNeovim sources them _after_ loading plugins.\n\n## :electric_plug: Pre-configured plugins\n\nThis configuration comes with [a few plugins pre-configured](./nix/neovim-overlay.nix).\n\nYou can add or remove plugins by\n\n- Adding/Removing them in the [Nix list](./nix/neovim-overlay.nix).\n- Adding/Removing the config in `nvim/plugin/\u003cplugin\u003e.lua`.\n\n## :anchor: Syncing updates\n\nIf you have used this template and would like to fetch updates\nthat were added later...\n\nAdd this template as a remote:\n\n```console\ngit remote add upstream git@github.com:nix-community/kickstart-nix.nvim.git\n```\n\nFetch and merge changes:\n\n```console\ngit fetch upstream\ngit merge upstream/main --allow-unrelated-histories\n```\n\n## :pencil: Editing your config\n\nWhen your neovim setup is a nix derivation, editing your config\ndemands a different workflow than you are used to without nix.\nHere is how I usually do it:\n\n- Perform modifications and stage any new files[^2].\n- Run `nix run /path/to/neovim/#nvim`\n  or `nix run /path/to/neovim/#nvim -- \u003cnvim-args\u003e`\n\n[^2]: When adding new files, nix flakes won't pick them up unless they\n      have been committed or staged.\n\nThis requires a rebuild of the `nvim` derivation, but has the advantage\nthat if anything breaks, it's only broken during your test run.\n\nIf you want an impure, but faster feedback loop,\nyou can use `$XDG_CONFIG_HOME/$NVIM_APPNAME`[^3], where `$NVIM_APPNAME` \ndefaults to `nvim` if the `appName` attribute is not set \nin the `mkNeovim` function.\n\n[^3]: Assuming Linux. Refer to `:h initialization` for Darwin.\n\nThis has one caveat: The wrapper which nix generates for the derivation\ncalls `nvim` with `-u /nix/store/path/to/generated-init.lua`.\nSo it won't source a local `init.lua` file.\nTo work around this, you can put scripts in the `plugin` or `after/plugin` directory.\n\n\u003e [!TIP]\n\u003e\n\u003e If you are starting out, and want to test things without having to\n\u003e stage or commit new files for changes to take effect,\n\u003e you can remove the `.git` directory and re-initialize it (`git init`)\n\u003e when you are done.\n\n## :link: Alternative / similar projects\n\n- [`kickstart.nvim`](https://github.com/nvim-lua/kickstart.nvim):\n  Single-file Neovim configuration template with a similar philosophy to this project.\n  Does not use Nix to manage plugins.\n- [`neovim-flake`](https://github.com/jordanisaacs/neovim-flake):\n  Configured using a Nix module DSL.\n- [`NixVim`](https://github.com/nix-community/nixvim):\n  A module system for Neovim, with a focus on plugin configs.\n- [`nixCats-nvim`](https://github.com/BirdeeHub/nixCats-nvim):\n  A project that organises plugins into categories.\n  It also separates lua and nix configuration.\n- [`lz.n`](https://github.com/nvim-neorocks/lz.n):\n  A plugin-manager agnostic Lua library for lazy-loading plugins.\n  Can be used with Nix.\n\n\u003e [!NOTE]\n\u003e\n\u003e When comparing with projects in the \"non-Nix world\", this\n\u003e repository would be more comparable to `kickstart.nvim` (hence the name),\n\u003e while the philosophies of `neovim-flake` and `NixVim` are more in line with\n\u003e a Neovim distribution like [`LunarVim`](https://www.lunarvim.org/)\n\u003e or [`LazyVim`](https://www.lazyvim.org/)\n\u003e (though they are far more minimal by default).\n\n\u003c!-- MARKDOWN LINKS \u0026 IMAGES --\u003e\n[neovim-shield]: https://img.shields.io/badge/NeoVim-%2357A143.svg?\u0026style=for-the-badge\u0026logo=neovim\u0026logoColor=white\n[neovim-url]: https://neovim.io/\n[nix-shield]: https://img.shields.io/badge/nix-0175C2?style=for-the-badge\u0026logo=NixOS\u0026logoColor=white\n[nix-url]: https://nixos.org/\n[lua-shield]: https://img.shields.io/badge/lua-%232C2D72.svg?style=for-the-badge\u0026logo=lua\u0026logoColor=white\n[lua-url]: https://www.lua.org/\n[license-shield]: https://img.shields.io/github/license/nix-community/kickstart-nix.nvim.svg?style=for-the-badge\n[license-url]: https://github.com/nix-community/kickstart-nix.nvim/blob/master/LICENSE\n[issues-shield]: https://img.shields.io/github/issues/nix-community/kickstart-nix.nvim.svg?style=for-the-badge\n[issues-url]: https://github.com/nix-community/kickstart-nix.nvim/issues\n[license-shield]: https://img.shields.io/github/license/nix-community/kickstart-nix.nvim.svg?style=for-the-badge\n[license-url]: https://github.com/nix-community/kickstart-nix.nvim/blob/master/LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frayslash%2Fnvim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frayslash%2Fnvim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frayslash%2Fnvim/lists"}