nix-wrapper-modules

nix-wrapper-modules is a Nix library designed to create wrapped executables using the Nix module system.

Instead of manually writing shell scripts with pkgs.writeShellScriptBin or complex pkgs.symlinkJoin derivations to wrap programs with specific configurations (like custom config files or environment variables), this library allows you to define these wrappers as portable Nix modules.

Use this library when:

• You want to create a portable derivation of a program with specific settings (e.g., a specific shell for Alacritty).
• You want to avoid the overhead of pulling in entire NixOS or Home Manager configurations just to use a few configured tools.
• You need a consistent, flexible way to wrap packages that remains overrideable via the module system.
• You want to replace standard packages with wrapped versions in an overlay without losing the ability to use .override or .overrideAttrs.

Plugins are managed through the config.specs option. This option accepts a set of plugins or a set of lists of plugins.

There are two primary ways to organize plugins:

1. Startup Plugins: Provided as a simple list of plugins (e.g., specs.general = [ plugin1 plugin2 ];).
2. Lazy-loaded Plugins: Provided as a spec object where you can set lazy = true and pass the plugin list in the .data field.

Each item in a spec can be customized using:

• config.specMods: For customizing the plugin spec.
• config.specCollect: For processing specs.
• config.specMaps: For advanced mapping of specs.

Note: Plugins can be in-store or out-of-store paths, but they cannot be inline Lua values.

# Basic plugin specification example
specs.general = with pkgs.vimPlugins; [ 
  # plugins loaded at startup 
];

specs.lazy = {
  lazy = true;
  data = with pkgs.vimPlugins; [
    # plugins loaded via vim.cmd.packadd
  ];
};

In the Neovim wrapper module, plugins are managed using the config.specs option. This option accepts a set of plugins or a set of lists of plugins.

Instead of passing a raw plugin package, you can pass a spec (an attribute set) to provide additional metadata like configuration code, loading behavior, or language types.

Key behaviors:

• Direct Plugin: Pass the package directly (e.g., config.specs.name = pkgs.plugin).
• Spec Object: Pass an attribute set where the plugin is assigned to the data field.
• Propagation: Many options set in the outer attribute set (the parent) will propagate to all contained lists/specs. For example, setting lazy = true in a parent spec will make all plugins in its data list load lazily by default.

# Direct plugin path
config.specs.gitsigns = pkgs.vimPlugins.gitsigns-nvim;

# Spec with configuration
config.specs.treesj = {
  data = pkgs.vimPlugins.treesj;
  config = "require('treesj').setup({})";
};

# List of specs with propagation
config.specs.completion-plugins = {
  lazy = true; # This propagates to all items in the 'data' list
  data = [
    {
      name = "blink-cmp";
      data = pkgs.vimPlugins.blink-cmp;
    }
    pkgs.vimPlugins.fzf-lua-nvim;
  ];
};

The Neovim wrapper makes Nix-provided information available in your Lua configuration through a plugin. The plugin is accessible via the global variable vim.g.nix_info_plugin_name.

To access values, use the fetcher function pattern: nixInfo(default, "path", "to", "value", "in", "plugin").

Recommended pattern for non-Nix compatibility: To prevent errors when running Neovim outside of a Nix environment, wrap the requirement in a pcall and provide a fallback function that returns the default value.

-- Accessing values
local nixInfo = require(vim.g.nix_info_plugin_name)
local default = nil
local value = nixInfo(default, "path", "to", "value", "in", "plugin")

-- Non-Nix compatibility shim
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