### Basic Neovim Module Configuration

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/pre_desc.md

Example configuration showing how to import the module, define plugin specs, set info values, and configure runtime packages.

```nix
{ wlib, config, pkgs, lib, ... }:
  imports = [ wlib.wrapperModules.neovim ];
  specs.general = with pkgs.vimPlugins; [
    # plugins which are loaded at startup ...
  ];
  specs.lazy = {
    lazy = true;
    data = with pkgs.vimPlugins; [
      # plugins which are not loaded until you vim.cmd.packadd them ...
    ];
  };
  info = {
    values = "for lua";
    which = "will be placed in the generated info plugin for access";
  };
  runtimePkgs = with pkgs; [
    # lsps, formatters, etc...
  ];
  settings.config_directory = ./.; # or lib.generators.mkLuaInline "vim.fn.stdpath('config')";
}
```

--------------------------------

### Wrap MPV with Configuration and Scripts

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/ci/docs/md/getting-started.md

This example shows how to wrap the `mpv` package using `wrappers.wrappers.mpv.wrap`, providing custom configuration options for `mpv.conf`, `mpv.input`, and including `mpvScripts.mpris`.

```nix
{ 
  description = ''
    A flake providing a wrapped `mpv` package with some configuration
  '';
  inputs.wrappers.url = "github:BirdeeHub/nix-wrapper-modules";
  inputs.wrappers.inputs.nixpkgs.follows = "nixpkgs";
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
  outputs = { self, nixpkgs, wrappers }:
    let
      forAllSystems = with nixpkgs.lib;
      genAttrs platforms.all;
    in
      {
        packages = forAllSystems (system: {
          default = wrappers.wrappers.mpv.wrap (
            {config, wlib, lib, pkgs, ...}:
              {
                pkgs = import nixpkgs { inherit system; };
                scripts = [ pkgs.mpvScripts.mpris ];
                "mpv.conf".content = ''
                  vo=gpu
                  hwdec=auto
                '';
                "mpv.input".content = ''
                  WHEEL_UP seek 10
                  WHEEL_DOWN seek -10
                '';
              }
          );
        });
      };
}

```

--------------------------------

### Wrap Wezterm with Custom Keybinds

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/ci/docs/md/getting-started.md

This example demonstrates how to use `evalPackage` to create a wrapped `wezterm` package with a custom keybind defined in `luaInfo`.

```nix
{ 
  description = ''
    A flake providing a wrapped `wezterm` package with an extra keybind!
  '';
  inputs.wrappers.url = "github:BirdeeHub/nix-wrapper-modules";
  outputs = { self, wrappers }:
    {
      # These things work without flakes too,
      # but this gives an example from start to finish!
      packages.x86_64-linux.default = wrappers.lib.evalPackage
        ({ config, lib, wlib, pkgs, ... }:
          {
            pkgs = wrappers.inputs.nixpkgs.legacyPackages.x86_64-linux;
            imports = [ wlib.wrapperModules.wezterm ];
            luaInfo = {
              keys = [
                {
                  key = "F12";
                  mods = "SUPER|CTRL|ALT|SHIFT";
                  action = lib.generators.mkLuaInline "wezterm.action.Nop";
                }
              ];
            };
          });
    };
}

```

--------------------------------

### Integrating Wrapper Modules into Home Manager Configuration

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/ci/docs/md/getting-started.md

Use `getInstallModule` to integrate wrapper modules into your Home Manager configuration. This example configures the `neovim` wrapper with custom settings and plugins.

```nix
# in a home-manager module
{ config, lib, ... }:
{
  imports = [
    (inputs.wrappers.lib.getInstallModule {
      name = "neovim";
      value = inputs.wrappers.lib.wrapperModules.neovim;
    })
  ];
  wrappers.neovim = { pkgs, lib, ... }: {
    enable = true;
    settings.config_directory = ./nvim;
    specs.stylix = {
      data = pkgs.vimPlugins.mini-base16;
      before = [ "INIT_MAIN" ];
      info = lib.filterAttrs (
        k: v: builtins.match "base0[0-9A-F]" k != null
      ) config.lib.stylix.colors.withHashtag;
      config = /* lua */ ''
        local info, pname, lazy = ...
        require("mini.base16").setup({ palette = info, })
      '';
    };
  };
  home.sessionVariables = let
    # You can still grab the value from config if desired!
    nvimpath = lib.getExe config.wrappers.neovim.wrapper;
  in {
    EDITOR = nvimpath;
    MANPAGER = "${nvimpath} +Man!";
  };
}

```

--------------------------------

### Nix SymlinkJoin Wrapper Example

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/README.md

An example using symlinkJoin to wrap a program, attempting to include configuration files and potentially other assets. This approach is closer to how some Nix modules function but can still present challenges with overrides and metadata.

```nix
pkgs.symlinkJoin (let
  tomlcfg = pkgs.writeText "alacritty.toml" ''
    [terminal.shell]
    program = "${pkgs.zsh}/bin/zsh"
    args = [ "-l" ]
  '';
in {
  name = "alacritty";
  paths = [ pkgs.alacritty ];
  nativeBuildInputs = [ pkgs.makeWrapper ];
  postBuild = ''
    wrapProgram $out/bin/alacritty --add-flag --config-file --add-flag ${tomlcfg}
  '';
})
```

--------------------------------

### Nix Module Example with File Generation

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/CONTRIBUTING.md

Demonstrates how to define Nix module options, generate a configuration file using `constructFiles`, and integrate it with `wlib.types.file`. This pattern ensures placeholders work correctly by constructing the file path within the final wrapper derivation.

```nix
{ config,
  lib,
  wlib,
  pkgs,
  ... 
}:
{
  imports = [ wlib.modules.default ];
  options = {
    settings = lib.mkOption {
      inherit (pkgs.formats.gitIni { }) type;
      default = { };
      description = ''
        Git configuration settings.
        See {manpage}`git-config(1)` for available options.
      '';
    };
    configFile = lib.mkOption {
      type = wlib.types.file {
        # we can refer to the placeholder of our constructed file!
        path = lib.mkOptionDefault config.constructFiles.gitconfig.path;
      };
      default = { };
      description = "Generated git configuration file.";
    };
  };
  config = {
    env.GIT_CONFIG_GLOBAL = config.configFile.path;
    package = lib.mkDefault pkgs.git;
    constructFiles.gitconfig = { # <- constructs the path directly in the final wrapper derivation, such that placeholders work correctly.
      relPath = "${config.binName}config";
      # A string, which is to become the file contents
      content =
        # nixpkgs has a lot of handy generation functions!
        lib.generators.toGitINI config.settings
        # and gitconfig format allows you to arbitrarily append contents!
        + "\n" + config.configFile.content;
    };
    meta.maintainers = [ wlib.maintainers.birdee ]; # <- don't forget to make yourself the maintainer of your module!
  };
}
```

--------------------------------

### Basic Nix Shell Script Wrapper

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/README.md

Creates a shell script to launch a program with a specific configuration file. This method installs a wrapper script instead of the original program.

```nix
pkgs.writeShellScriptBin "alacritty" (let
  tomlcfg = pkgs.writeText "alacritty.toml" ''
    [terminal.shell]
    program = "${pkgs.zsh}/bin/zsh"
    args = [ "-l" ]
  '';
in ''
  exec ${pkgs.alacritty}/bin/alacritty --config-file ${tomlcfg} "$@"
'')
```

--------------------------------

### Integrate Neovim Module into Existing Configuration

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/templates/neovim/README.md

Example of how to call the neovim module directly from another Nix configuration, useful if you don't want a separate flake. This example shows NixOS integration.

```nix
inputs: # <-- get the library somehow
{ pkgs, ... }:
{
  # call the module and install the package (nixos example)
  environment.systemPackages = [ (inputs.nix-wrapper-modules.lib.evalPackage [ ./module.nix { inherit pkgs; } ]) ];
}
```

--------------------------------

### Example Usage of Tmux Wrapper Module

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/ci/docs/md/wrapper-modules.md

Demonstrates how to use a partially evaluated wrapper module for tmux to quickly build a package with a specific configuration. The resulting package can be further modified by calling `.wrap` on it.

```nix
inputs.nix-wrapper-modules.wrappers.tmux.wrap { inherit pkgs; prefix = "C-Space"; }
```

--------------------------------

### Quickly Creating a One-Off Wrapped Program

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/ci/docs/md/getting-started.md

Use `wrapPackage` for a convenient way to create a single wrapped program within your Nix configuration. This example wraps `pkgs.curl` with custom environment variables and flags.

```nix
inputs: # <- get the lib somehow
{ pkgs, ... }: {
  home.shellAliases = let
    curlwrapped = inputs.wrappers.lib.wrapPackage ({ config, wlib, lib, ... }: {
      inherit pkgs; # you can only grab the final package if you supply pkgs!
      package = pkgs.curl;
      runtimePkgs = [ pkgs.jq ];
      env = {
        CURL_CA_BUNDLE = "${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt";
      };
      flags = {
        "--silent" = true;
        "--connect-timeout" = "30";
      };
      flagSeparator = "=";  # Use --flag=value instead of --flag value (default is " ")
      runShell = [
      ''
        echo "Making request..." >&2
      ''
      ];
    });
  in {
    runCurl = "${lib.getExe curlwrapped}";
  };
}

```

--------------------------------

### Creating a Custom Wrapper Module with Nix

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/ci/docs/md/getting-started.md

Define a custom wrapper module using `evalModule`. This example shows how to configure FFmpeg with custom options for profile, output directory, and preset flags.

```nix
inputs:
(inputs.wrappers.lib.evalModule ({ config, wlib, lib, pkgs, ... }: {
  # You can only grab the final package if you supply pkgs!
  # But if you were making it for someone else, you would want them to do that!

  # config.pkgs = pkgs;

  # include wlib.modules.makeWrapper and wlib.modules.symlinkScript
  imports = [ wlib.modules.default ];
  # The core options are focused on building a wrapper derivation.
  # different wrapper options may be implemented on top, for things like bubblewrap or other tools.
  # `wlib.modules.default` gives you a great module-based pkgs.makeWrapper to use.

  options = {
    profile = lib.mkOption {
      type = lib.types.enum [ "fast" "quality" ];
      default = "fast";
      description = "Encoding profile to use";
    };
    outputDir = lib.mkOption {
      type = lib.types.str;
      default = "./output";
      description = "Directory for output files";
    };
  };

  config.package = pkgs.ffmpeg;
  config.flags = {
    "-preset" = if config.profile == "fast" then "veryfast" else "slow";
  };
  config.env = {
    FFMPEG_OUTPUT_DIR = config.outputDir;
  };
})) # .config.wrapper to grab the final package! Only works if pkgs was supplied.

```

--------------------------------

### Integrating Wrapper Modules into NixOS Configuration

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/ci/docs/md/getting-started.md

Import wrapper modules directly into your NixOS configuration using `getInstallModule`. This example shows how to enable and configure the `tmux` wrapper.

```nix
# in a nixos module
{ ... }:
{
  imports = [
    (inputs.wrappers.lib.getInstallModule { name = "tmux"; value = inputs.wrappers.lib.wrapperModules.tmux; })
  ];
  wrappers.tmux = {
    enable = true;
    modeKeys = "vi";
    statusKeys = "vi";
    vimVisualKeys = true;
  };
}

```

--------------------------------

### Getting Nix Plugin Path in Lua

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

This Lua function helps determine if a plugin was installed by Nix. It queries the info plugin for both lazy-loaded and start plugins.

```lua
local nixInfo = require(vim.g.nix_info_plugin_name)
local function get_nix_plugin_path(name)
  return nixInfo(nil, "plugins", "lazy", name) or nixInfo(nil, "plugins", "start", name)
end
```

--------------------------------

### Preventing Path Collisions (Nix)

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

Set `config.settings.dont_link` to `true` in your Nix configuration to prevent path collisions when multiple Neovim derivations are installed.

```nix
# set this to true
config.settings.dont_link = true;
```

--------------------------------

### Accessing Exposed Specs in Lua

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

Retrieve information about exposed specs from the info plugin in your Lua configuration. This example checks for the presence of a 'cat' spec.

```lua
local nixInfo = require(vim.g.nix_info_plugin_name)
local cat_is_present = nixInfo(false, "info", "cats", "<specs_attribute_name>")
```

--------------------------------

### Test Helper Module or Library Function

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/CONTRIBUTING.md

When testing helper modules or library functions, use the `test` function with an arbitrary name instead of a wrapper name. This example shows how to name a test and define assertions.

```nix
{ pkgs, self, tlib, ... }:

let
  inherit (tlib)
    fileContains
    isDirectory
    isFile
    notIsFile
    areEqual
    test
    ;
in
test "my-test" { # <-- Specify an arbitrary name for your test
# test { name = "my-test" } { # <-- This is equivalent

  "my first test" = [ ... ]; # <-- nothing new here
  "my second test" = [ ... ];
}

```

--------------------------------

### Test Nix Wrapper Module

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/CONTRIBUTING.md

When testing a wrapper module, specify the wrapper name in the `test` function to ensure tests run on the correct platforms. This example demonstrates testing the 'direnv' wrapper with various assertions.

```nix
{ pkgs, self, tlib, ... }:

let
  inherit (tlib)
    fileContains
    isDirectory
    isFile
    notIsFile
    areEqual
    test
    ;
in
test { wrapper = "direnv"; } { # <-- Specify the name of the wrapper here (*)

  "direnv wrapper should be created" =
    let
      wrapper = self.wrappers.direnv.wrap {
        inherit pkgs;
        nix-direnv.enable = true;
      };
    in
    [
      "[[ -d ${wrapper} ]]" # <-- a simple condition to be asserted
      {
        cond = "[[ -d ${wrapper} ]]" ;
        msg = "No directory found for wrapper."; # <-- you can also specify a custom error message
      }
      (isDirectory wrapper) # <-- or use pre-defined helpers
    ];

  "wrapper should output correct version" =
    let
      wrapper = self.wrappers.direnv.wrap {
        inherit pkgs;
      };
    in 
    '' # <-- no need to provide a list if there is only one assertion
      "${wrapper}/bin/direnv" --version |
      grep -q "${wrapper.version}"
    '';

  "math-tests" = { # <-- tests can be arbitrarily grouped
    addition = [
      (areEqual 2 (1 + 1))
      (areEqual 7 (5 + 2))
    ];
    multiplication = [
      (areEqual 1 (1 * 1))
      (areEqual 10 (5 * 2))
    ];
  };
}

```

--------------------------------

### Lua Code Snippet with Options and Data

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/x/xplr/luaInit-desc.md

Define a Lua code snippet with specific options and data. The 'opts' are passed to the Lua environment, and the 'data' field contains the Lua code to be executed. This example demonstrates returning hooks.

```lua
local opts, name = ...
print(name, require("inspect")(opts), "${placeholder \"out\"}")
return opts.hooks -- xplr configurations can return hooks
```

--------------------------------

### Fennel Code Snippet with Options and Data

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/x/xplr/luaInit-desc.md

Define a Fennel code snippet with specific options and data, similar to Lua snippets. 'opts' are passed to the Fennel environment, and 'data' contains the Fennel code. This example also demonstrates returning hooks.

```fennel
(local (opts name) ...)
(print name ((require "inspect") opts) "${placeholder \"out\"}")
(. opts hooks) ;; xplr configurations can return hooks
```

--------------------------------

### Modifying Spec Defaults with specMods

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

Applies modifications to the default values of spec fields using `config.specMods`. This example shows how to set a default for `collateGrammars`, allowing parent values to propagate to child specs. The `parentSpec` argument is `null` for the outer set and receives the `config` argument for inner lists.

```nix
config.specMods = { parentSpec, ... }:
{
  config.collateGrammars = lib.mkDefault (parentSpec.collateGrammars or false);
};
```

--------------------------------

### Extend and Apply Tmux Configurations

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/ci/docs/md/getting-started.md

Demonstrates extending an initial `tmux` configuration using `.eval`, `.apply`, and `.wrap`. It shows how to add plugins, modify keybindings, and access the final wrapped package.

```nix
# Apply initial configuration
# you can use `.eval` `.apply` or `.wrap` for this.
initialConfig = (inputs.wrappers.wrappers.tmux.eval ({config, pkgs, ...}{
  # but if you don't plan to provide pkgs yet, you can't use `.wrap` or `.wrapper` yet.
  # config.pkgs = pkgs;
  # but we can still use `pkgs` before that inside!
  config.plugins = [ pkgs.tmuxPlugins.onedark-theme ];
  config.clock24 = false;
})).config;

# Extend with additional configuration!
extendedConfig = initialConfig.apply {
  modeKeys = "vi";
  statusKeys = "vi";
  vimVisualKeys = true;
};

# Access the wrapper!
# apply is useful because we don't need to give it `pkgs` but it gives us
# top level access to `.wrapper`, `.wrap`, `.apply`, and `.eval`
# without having to grab `.config` ourselves
actualPackage = extendedConfig.wrap { inherit pkgs; };
# since we didn't supply `pkgs` yet, we must pass it `pkgs`
# before we are given the new value of `.wrapper` from `.wrap`

# Extend it again! You can call them on the package too!
apackage = (actualPackage.eval {
  prefix = "C-Space";
}).config.wrapper; # <-- `.wrapper` to access the package direcly

# and again! `.wrap` gives us back the package directly
# all 3 forms take modules as an argument
packageAgain = apackage.wrap ({config, pkgs, ...}: {
  # list definitions append when declared across modules by default!
  plugins = [ pkgs.tmuxPlugins.fzf-tmux-url ];
});

```

--------------------------------

### Initialize Neovim Template

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/pre_desc.md

Command to initialize the Neovim template using a Nix flake.

```bash
nix flake init -t github:BirdeeHub/nix-wrapper-modules#neovim
```

--------------------------------

### Simplified Neovim Module Configuration

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/templates/neovim/README.md

A basic structure for a `module.nix` file for the Neovim wrapper. It demonstrates importing the module, defining startup and lazy-loaded plugins, and specifying runtime packages and the configuration directory.

```nix
{ wlib, config, pkgs, lib, ... }:
  imports = [ wlib.wrapperModules.neovim ];
  specs.general = with pkgs.vimPlugins;
    [ # plugins which are loaded at startup ...
    ];
  specs.lazy = {
    lazy = true;
    data = with pkgs.vimPlugins;
      [ # plugins which are not loaded until you vim.cmd.packadd them ...
      ];
  };
  runtimePkgs = with pkgs;
    [ # lsps, formatters, etc...
    ];
  settings.config_directory = ./.; # or lib.generators.mkLuaInline "vim.fn.stdpath('config')";
```

--------------------------------

### Importing External Plugin with nvim-lib.mkPlugin

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

Demonstrates how to use `nvim-lib.mkPlugin` to build a plugin from a Git flake input. Ensure the input is configured with `flake = false` if it's not a flake itself.

```nix
inputs.treesj = {
  url = "github:Wansmer/treesj";
  flake = false;
};

config.specs.treesj = config.nvim-lib.mkPlugin "treesj" inputs.treesj;
```

--------------------------------

### Initialize Flake with flake-parts Template

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/ci/docs/md/getting-started.md

Use this command to create a new flake project initialized with the flake-parts structure from the nix-wrapper-modules repository.

```bash
nix flake init -t github:BirdeeHub/nix-wrapper-modules#flake-parts
```

--------------------------------

### Basic Neovim Configuration

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

Sets the binary name for Neovim and initializes an empty list for aliases.

```nix
config.binName = "nvim";
config.settings.aliases = [ ];
```

--------------------------------

### Configuring Lua Initialization Order with Dependencies

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/x/xplr/luaInit-desc.md

Demonstrates how to set up multiple luaInit entries with dependencies. TESTFILE_2 depends on TESTFILE_1, ensuring TESTFILE_1 runs first. The 'type' field specifies the language (e.g., 'fnl' for Fennel).

```nix
luaInit.TESTFILE_1 = {
  opts = { testval = 1; };
  data = /* lua */''
    local opts, name = ...
    print(name, require("inspect")(opts), "${placeholder \"out\"}")
    return opts.hooks -- xplr configurations can return hooks
  '';
};
luaInit.TESTFILE_2 = {
  opts = { testval = 2; };
  after = [ "TESTFILE_1" ];
  type = "fnl";
  data = /* fennel */ ''
    (local (opts name) ...)
    (print name ((require "inspect") opts) "${placeholder \"out\"}")
    (. opts hooks) ;; xplr configurations can return hooks
  '';
};
```

--------------------------------

### Build Neovim Configuration

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/templates/neovim/README.md

Build the Neovim configuration package from the initialized flake directory.

```bash
nix build .
```

--------------------------------

### Direct Plugin Path Configuration

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/spec_desc.md

Assigns a plugin directly to a configuration key. This is the simplest way to add a plugin.

```nix
config.specs.gitsigns = pkgs.vimPlugins.gitsigns-nvim;
```

--------------------------------

### Basic Lua String Initialization

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/x/xplr/luaInit-desc.md

Use a simple string for luaInit when no specific options or ordering requirements are needed. The string content is directly assigned to config.luaInit.<name>.data.

```nix
luaInit.WillRunEventually = ''
  print([[ 
    you can also just put a string if you currently don't need opts,
    don't have ordering requirements, etc...

    config.luaInit.WillRunEventually.data will be this string.
    You can still add other stuff later.
  ]])
'';
```

--------------------------------

### Customizing Spec Options with specMods

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/spec_desc.md

Demonstrates how to use 'specMods' to define custom options and modify default behaviors for specs. It shows how parent spec options can be accessed and inherited by child specs.

```nix
config.specMods = { parentSpec, ... }: {
  # declare more spec fields you can process either here, or after with other options!
  options.myopt = lib.mkOption {
    type = lib.types.bool;
    default = parentOpts.myopt or false;
    desc = "A description for myopt";
  };
  # Or change a default!
  config.collateGrammars = parentSpec.collateGrammars or false;
  config.type = parentSpec.type or "fnl";
};
```

--------------------------------

### Run Site Generator Locally

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/CONTRIBUTING.md

Execute the site generator locally using `nix run ./ci`. Alternatively, use `nix run ./ci#docs` for documentation generation.

```bash
nix run ./ci
```

```bash
nix run ./ci#docs
```

--------------------------------

### Using pluginsFromPrefix to Load Multiple Plugins

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

Shows how to utilize the `pluginsFromPrefix` helper function to load multiple plugins from flake inputs. It imports the module containing the helper and then uses it to define `neovimPlugins`, which are subsequently assigned to specific specs.

```nix
inputs:
{ config, ... }:
let
  neovimPlugins = config.nvim-lib.pluginsFromPrefix "plugins-" inputs;
in {
  imports = [ ./the_above_module.nix ];
  specs.treesitter-textobjects = neovimPlugins.treesitter-textobjects;
}
```

--------------------------------

### Build Individual Wrapper Tests

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/CONTRIBUTING.md

Build tests for a specific wrapper module on a given system using `nix build ./ci#checks.{system}.wrapperModule-{name}`. Replace `{system}` and `{name}` with the target system and wrapper module name.

```bash
nix build ./ci#checks.x86_64-linux.wrapperModule-neovim
```

--------------------------------

### Exposing Settings to Info Plugin (Nix)

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

Define Nix options to expose settings, such as 'cats', to the info plugin. This allows Lua configurations to query these settings.

```nix
options.settings.cats = lib.mkOption {
  readOnly = true;
  type = lib.types.attrsOf lib.types.raw;
  default = builtins.mapAttrs (_: v: v.enable) config.specs;
};
# nixInfo(false, "settings", "cats", "<specs_attribute_name>")
```

--------------------------------

### Format Code with Nix

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/CONTRIBUTING.md

Use the `nix fmt` command to format your Nix code according to project standards.

```bash
nix fmt
```

--------------------------------

### Flake Configuration with flake-parts

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/ci/docs/md/getting-started.md

This Nix flake configuration demonstrates how to use flake-parts to set up wrapper modules for applications like Alacritty, Xplr, and Tmux. It shows how to import wrapper modules, configure application settings, and control package outputs.

```nix
{ 
  description = ''
    Uses flake-parts to set up the flake outputs:

    `wrappers`, `wrapperModules` and `packages.*.*`
  '';
  inputs.wrappers.url = "github:BirdeeHub/nix-wrapper-modules";
  inputs.wrappers.inputs.nixpkgs.follows = "nixpkgs";
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
  inputs.flake-parts.url = "github:hercules-ci/flake-parts";
  inputs.flake-parts.inputs.nixpkgs-lib.follows = "nixpkgs";
  outputs = 
    { 
      self, 
      nixpkgs, 
      wrappers, 
      flake-parts, 
      ... 
    }@inputs:
    flake-parts.lib.mkFlake { inherit inputs; } { 
      systems = nixpkgs.lib.platforms.all;
      # Import the flake-parts module:
      imports = [ wrappers.flakeModules.wrappers ];

      # provide wrapper modules to flake.wrappers
      flake.wrappers.alacritty = { pkgs, wlib, ... }: { 
        imports = [ wlib.wrapperModules.alacritty ];
        settings.terminal.shell.program = "${pkgs.zsh}/bin/zsh";
        settings.terminal.shell.args = [ "-l" ];
      };
      flake.wrappers.xplr = wrappers.lib.wrapperModules.xplr;
      flake.wrappers.tmux = 
        { wlib, pkgs, ... }:
        { 
          imports = [ wlib.wrapperModules.tmux ];
          plugins = with pkgs.tmuxPlugins; [ onedark-theme ];
        };

      flake.wrappers.tmux-modified = {
        # using flake.wrappers will also make importable forms
        # available in config.flake.wrapperModules!
        imports = [ self.wrapperModules.tmux ];
        # these will add to the above config which added the onedark-theme plugin
        modeKeys = "vi";
        statusKeys = "vi";
        vimVisualKeys = true;
      };

      # no need for getInstallModule with flake-parts!
      flake.nixosModules = builtins.mapAttrs (_: v: v.install) self.wrappers;
      flake.homeModules = self.nixosModules;
      # you don't have to export them from there specifically,
      # this just shows that you can access `.install` directly when using the flake-parts module

      # (optionally) Control which packages get built!
      perSystem = 
        { pkgs, ... }:
        {
          # wrappers.pkgs = pkgs; # (optionally) choose a different `pkgs`
          wrappers.control_type = "exclude"; # | "build" (default: "exclude")
          wrappers.packages = { 
            tmux-modified = true; # <- set to true to exclude from being built into `packages.*.*` flake output
          };
        };
    };
}
```

--------------------------------

### Nix Wrapper Module Usage

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/README.md

Demonstrates the usage of a Nix wrapper module for configuring a program like Alacritty. This method leverages the Nix module system for flexible and reusable configurations, supporting overrides and metadata management.

```nix
inputs.nix-wrapper-modules.wrappers.alacritty.wrap {
  inherit pkgs;
  settings.terminal.shell.program = "${pkgs.zsh}/bin/zsh";
  settings.terminal.shell.args = [ "-l" ];
}
```

--------------------------------

### Helper Function for Building Multiple External Plugins

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

Provides a helper function `pluginsFromPrefix` within `config.nvim-lib` to efficiently build multiple plugins from flake inputs that share a common prefix. This is useful for organizing and managing numerous external plugins.

```nix
{ config, lib, ... }:
{
  options.nvim-lib.pluginsFromPrefix = lib.mkOption {
    type = lib.types.raw;
    readOnly = true;
    default =
      prefix: inputs:
      lib.pipe inputs [
        builtins.attrNames
        (builtins.filter (s: lib.hasPrefix prefix s))
        (map (
          input:
          let
            name = lib.removePrefix prefix input;
          in
          {
            inherit name;
            value = config.nvim-lib.mkPlugin name inputs.${input};
          }
        ))
        builtins.listToAttrs
      ];
  };
}
```

--------------------------------

### Neovide Host Configuration

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

Configures the Neovide host for Neovim, enabling it and setting the Neovim binary path.

```nix
config.hosts.neovide = 
  { lib,
    wlib,
    pkgs,
    ... 
  }:
  {
    imports = [ wlib.modules.default ];
    config.nvim-host.enable = lib.mkDefault false;
    config.package = pkgs.neovide;
    # also offers nvim-host wrapper arguments which run in the context of the final nvim drv!
    config.nvim-host.flags."--neovim-bin" = config.wrapperPaths.placeholder;
  };

  # This one is included!
  # To add a wrapped ${placeholder config.outputName}/bin/${config.binName}-neovide to the resulting neovim derivation
  config.hosts.neovide.nvim-host.enable = true;
```

--------------------------------

### Non-Nix Plugin Compatibility Check

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

Ensures plugin compatibility when not using Nix by conditionally loading the plugin or providing a fallback.

```lua
do
  local ok = pcall(require, vim.g.nix_info_plugin_name)
  if not ok then
    package.loaded[vim.g.nix_info_plugin_name] = setmetatable({}, {
      __call = function (_, default) return default end
    })
  end
  require(vim.g.nix_info_plugin_name).isNix = vim.g.nix_info_plugin_name ~= nil
end
```

--------------------------------

### Using a Different Neovim Version (Nix)

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

Configure the Neovim package to use a specific version, such as a nightly build, by setting `config.package` to the desired Neovim derivation.

```nix
config.package = inputs.neovim-nightly-overlay.packages.${pkgs.stdenv.hostPlatform.system}.neovim;
```

--------------------------------

### Integrating Runtime Packages into Specs

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

Demonstrates how to include runtime packages, such as language servers, within Neovim specs. It defines a `runtimePkgs` spec field and collects these packages to be added to the PATH for the Neovim derivation. If a spec is disabled, its `runtimePkgs` will not be included.

```nix
{ config, lib, wlib, options, ... }:
{
  config.specMods = {
    options.runtimePkgs = options.runtimePkgs // {
      description = ''
        A runtimePkgs spec field to put packages on the PATH
        If the spec is disabled, this value will not be included in the resulting neovim derivation
      '';
    };
  };
  config.runtimePkgs = config.specCollect (acc: v: acc ++ (v.runtimePkgs or [ ])) [ ];
}
```

--------------------------------

### Exposing Specs to Info Plugin (Nix)

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

Configure the info plugin to expose top-level specs. This Nix code maps attribute names to their enablement status.

```nix
config.info.cats = builtins.mapAttrs (_: v: v.enable) config.specs;
```

--------------------------------

### Check Nix Flake Configuration

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/CONTRIBUTING.md

Perform a comprehensive check of the Nix flake configuration using `nix flake check -Lv ./ci`.

```bash
nix flake check -Lv ./ci
```

--------------------------------

### Spec with Fennel Config and Lua Info

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/spec_desc.md

Configures a plugin using a spec object with Fennel for the 'config' and Lua for 'info'. The 'mkLuaInline' helper is used to embed Lua code within the info.

```nix
# Spec with info values (in fennel!)
config.specs.lualine = {
  data = pkgs.vimPlugins.lualine-nvim;
  type = "fnl";
  info = { # mkLuaInline in info still just makes lua even if its fennel type
    theme = lua.mkLuaInline "[[catppuccin]]";
  };
  # but here we can use fennel!
  config = ''
    (local (opts name) ...)
    ((. (require "lualine") setup) {
      :options { :theme info.theme }
    })
  '';
};
```

--------------------------------

### Spec Definition with Data and Config

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/spec_desc.md

Defines a plugin using a spec object, providing its package in 'data' and configuration code in 'config'. The config is in Lua.

```nix
config.specs.treesj = {
  data = pkgs.vimPlugins.treesj;
  config = "require('treesj').setup({})";
};
```

--------------------------------

### Loading Lazy-Loaded Plugins (Lua)

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

Use `vim.cmd.packadd` in Lua to manually load plugins that have been marked as lazy. This is useful for controlling plugin load times.

```lua
vim.cmd.packadd("<pname>")
```

--------------------------------

### List of Specs with Propagation

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/spec_desc.md

Defines a list of plugin specs, where the 'lazy' option propagates to all contained specs. Individual specs can be defined directly or as objects.

```nix
# List of specs (DAL inside the DAG)
config.specs.completion-plugins = {
  lazy = true; # lazy will propagate to the contained specs.
  data = [
    {
      name = "blink-cmp";
      data = pkgs.vimPlugins.blink-cmp;
    }
    # values can be specs or plugins here too!
    # some values will propagate from the parent.
    # you can change this, or add your own options via `config.specMods`!
    pkgs.vimPlugins.fzf-lua-nvim;
  ];
};
```

--------------------------------

### Accessing Nix Info in Lua

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

Use this snippet to retrieve information from the Nix environment within your Lua configuration. The `nixInfo` function takes a default value and a path to the desired value.

```lua
local nixInfo = require(vim.g.nix_info_plugin_name)
local default = nil
local value = nixInfo(default, "path", "to", "value", "in", "plugin")
```

--------------------------------

### Stylix Colorscheme Integration

Source: https://github.com/birdeehub/nix-wrapper-modules/blob/main/wrapperModules/n/neovim/post_desc.md

Integrates Stylix colors into Neovim using the mini-base16 plugin, applying colors before the main initialization.

```nix
{ pkgs, ... }:
{
  config.specs.base16 = {
    # install a plugin to handle the colors
    data = pkgs.vimPlugins.mini-base16;
    # run before the main init.lua
    before = [ "INIT_MAIN" ];

    # get the colors from your system and pass it
    info = pkgs.lib.filterAttrs (
      k: v: builtins.match "base0[0-9A-F]" k != null
    ) your-system-config.lib.stylix.colors.withHashtag;

    # call the plugin with the colors
    config = /* lua */ ''
      local info, pname, lazy = ...
      require("mini.base16").setup({
        palette = info,
      })
    '';
  };
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.