DOCSEARCHbyAlgolia
Submit Docs

nixCats-nvim

repository·main·Indexed 20 days ago

https://github.com/birdeehub/nixcats-nvim

A tool for managing Neovim configurations using Nix, following the philosophy of 'install with nix, configure with lua'. It allows users to leverage Nix for dependency management and plugin installation while maintaining a standard Lua-based configuration workflow. The project is currently in maintenance mode, with migration recommended to nix-wrapper-modules.

Tokens
4.7K
Snippets
11
Records
25
Agent score
72%

What's inside nixCats-nvim

  1. Overview of the nixCats builder

    main
    The builder directory contains the core logic for the nixCats builder. It is responsible for driving the category and message passing scheme, as well as managing the entire wrapper process. The builder is exported via the utils set defined in utils/default.nix.

  2. Understand the nixCats lazy wrapper and lazy.nvim compatibility

    main

    The nixCats lazy wrapper is provided to resolve conflicts between lazy.nvim and Nix. While lazy.nvim works with Nix, it can block Nix from installing plugins independently unless they are also defined as lazy.nvim plugin specs with matching names.

    The wrapper works by:

    1. Informing lazy.nvim about the locations of assets managed by Nix.
    2. Setting compatibility options before calling the standard lazy.nvim setup function.

    Important Requirement: If you want to download a plugin from Nix instead of lazy.nvim, the name used by lazy.nvim must match the name provided by Nix. If the names do not match, lazy.nvim will ignore the Nix-provided version and attempt to download its own version.

  3. Understand the idiomatic nixCats-nvim configuration approach

    main

    The recommended way to use nixCats is to treat it as your primary plugin manager, replacing tools like lazy.nvim and mason.nvim. In this model, nixCats is responsible for downloading all plugins via Nix, and you use Neovim's native packpath methods for loading them.

    Key principles of this approach:

    • No duplication: Avoid using mason.nvim or lazy.nvim when Nix is involved to prevent conflicts between Nix and Neovim-based download managers.
    • Native loading: Leverage standard Neovim runtime paths and packpath for both startup and lazy loading.
    • Lazy loading: Use lze or lz.n for lazy loading instead of lazy.nvim.
    • Conditional loading: Plugins are only loaded if their respective category is enabled in your configuration.
    • Fallback capability: This structure allows you to maintain a working configuration using paq and mason if you need to run Neovim without Nix.

  4. How the nixCats Category scheme works

    main

    The nixCats scheme allows you to pass arbitrary data from Nix to your Neovim Lua configuration without using Nix string interpolation (which often breaks tooling). This is done via a three-step process:

    1. Define a Category: Create a new list in the appropriate section of categoryDefinitions (e.g., in the startupPlugins set).
    2. Enable the Category: Enable that category for your specific Neovim package in packageDefinitions and populate it with data.
    3. Access in Lua: Use the nixCats() function in your Lua configuration to retrieve the data as a native Lua data structure.

    Note: You can pass any Nix data that is not an uncalled Nix function. Lua cannot execute Nix code, but it can consume the data structures passed to it.

    -- Accessing a category defined in Nix
local startup_plugins = nixCats('attr.path.to.yourList')

  5. Understand how files in the plugin directory are loaded

    main
    All files located within the templates/simple/plugin/ directory are executed automatically by Neovim at startup. This behavior is governed by Neovim's runtimepath ('rtp'). To ensure your configuration or plugin logic runs during the initialization phase, place your Lua files in this directory.

  6. Manage package names and $EDITOR variables

    main

    The name used to launch your Neovim build is determined by the package name defined in packageDefinitions within your Nix configuration.

    Important: If you change the package name to something other than nvim, you must update your $EDITOR environment variable. This is because the desktop file follows the package name, and external programs (like git) rely on the $EDITOR variable to locate your editor.

    Note that Neovim itself remains aware of its original path at <store_path>/bin/nvim and is not affected by the wrapper script name.

  8. Core Philosophy: Install with Nix, Configure with Lua

    main

    Unlike projects like nixvim or nvf which attempt to "nixify" the entire Neovim configuration, nixCats follows a hybrid approach:

    • Nix's Role: Manages the installation of Neovim and its dependencies (plugins, binaries, etc.) to ensure portability and dependency management.
    • Lua's Role: Handles the actual configuration of plugins and editor settings using standard Neovim Lua APIs.

    This approach provides a high-quality experience that feels like a regular Neovim setup (using a plugin manager + Mason) while benefiting from the reproducibility and isolation of Nix.

  9. Access the nixCats library via nixCats.utils

    main

    The nixCats.utils set serves as the primary entry point and interface for the entire nixCats library. It is used to access the main builder function, create modules, generate flake outputs, and utilize various utilities for interacting with the Nix side of nixCats.

    Key characteristics:

    • No dependencies required: You can access this set without additional dependencies.
    • No arguments required: The set is accessible without passing arguments to it.
    • Core functionality: It provides the main builder function and tools for Nix-side integration.

  11. Important Nix Flake precautions

    main

    When working with Nix Flakes in a nixCats project, follow these best practices to avoid common errors:

    • Stage your changes: Always run git add . before running Nix commands. Anything not staged in Git will not be added to the Nix store and will be invisible to both Nix and Neovim.
    • Zsh Users: If you use Zsh, be aware of potential globbing issues when running Nix flake commands. Refer to the nixCats documentation for specific Zsh workarounds.
    • Flake Schema: Familiarize yourself with the Nix Flake schema, as this knowledge is essential when installing flake-based nixCats configurations into your main system configuration.

  12. Configure Treesitter grammars for nixCats lazy wrapper

    main

    When using the nixCats lazy wrapper, how you provide Treesitter grammars depends on whether you install them via lazy.nvim or via Nix.

    Option 1: Installing via lazy.nvim If you manage grammars through lazy.nvim, you must ensure a C compiler is available by adding it to your lspsAndRuntimeDeps section within your categoryDefinitions.

    Option 2: Installing via Nix If you install grammars via Nix, the nixCats lazy wrapper supports any method that eventually calls pkgs.neovimUtils.grammarToPlugin. Supported patterns include:

    • Using withAllGrammars on the treesitter plugin.
    • Using withPlugins with a specific list of plugins.
    • Using allGrammars within withPlugins.
    • Accessing grammarPlugins attributes.
    • Using pkgs.neovimUtils.grammarToPlugin directly on a grammar.
    pkgs.vimPlugins.nvim-treesitter.withAllGrammars
# or
pkgs.vimPlugins.nvim-treesitter.withPlugins (plugins: with plugins; [ 
  nix
  lua
  # etc...
]);
# or
pkgs.vimPlugins.nvim-treesitter.withPlugins (plugins: pkgs.vimPlugins.nvim-treesitter.allGrammars)
# or
builtins.attrValues pkgs.vimPlugins.nvim-treesitter.grammarPlugins
# or
pkgs.neovimUtils.grammarToPlugin pkgs.tree-sitter-grammars.somegrammar