{"all_yanked":false,"avatar_url":"https://avatars.githubusercontent.com/u/181582751","created_at":"2026-07-14T10:10:22.049358Z","description":"Purr — a lean Nix flake library","download_url":"https://api.flakehub.com/f/nixcafe/purr/0.1.73+rev-2e7e4d20a3e010180481ed79ea79a6510a41eaf5.tar.gz","labels":["nix-flake","flake-framework","flake-parts","auto-discovery","module-system","nix"],"mirrored":false,"org":"nixcafe","outputs":{"checks":{"doc":"The `checks` flake output contains derivations that will be built by `nix flake check`.\n","name":"checks","outputs":[{"outputs":[{"doc":null,"for_systems":["aarch64-darwin"],"path":["checks","aarch64-darwin","pre-commit"],"short_description":"","store_paths":{"out":"/nix/store/ns4av9qrkhwipvpci7kzpfg69pdpziz2-pre-commit-run"},"what":"CI test"},{"doc":null,"for_systems":["aarch64-darwin"],"path":["checks","aarch64-darwin","purr-tests"],"short_description":"","store_paths":{"out":"/nix/store/dvb9mzarx2wh2dbarcry0ivzrklhirb6-purr-tests"},"what":"CI test"}],"platform":"aarch64-darwin"},{"outputs":[{"doc":null,"for_systems":["aarch64-linux"],"path":["checks","aarch64-linux","pre-commit"],"short_description":"","store_paths":{"out":"/nix/store/fwrj3c9vrr4mv3sg9hq0fjbic8ipkzs0-pre-commit-run"},"what":"CI test"},{"doc":null,"for_systems":["aarch64-linux"],"path":["checks","aarch64-linux","purr-tests"],"short_description":"","store_paths":{"out":"/nix/store/35ihkm9niq80hbgb334mymf03g9qazk4-purr-tests"},"what":"CI test"}],"platform":"aarch64-linux"},{"outputs":[{"doc":null,"for_systems":["x86_64-linux"],"path":["checks","x86_64-linux","pre-commit"],"short_description":"","store_paths":{"out":"/nix/store/l5qv0cwx43mzqm7qv79l81s3z51mf927-pre-commit-run"},"what":"CI test"},{"doc":null,"for_systems":["x86_64-linux"],"path":["checks","x86_64-linux","purr-tests"],"short_description":"","store_paths":{"out":"/nix/store/ps4gg59hifv16368kfq912gh0b23c73i-purr-tests"},"what":"CI test"}],"platform":"x86_64-linux"}]},"devShells":{"doc":"The `devShells` flake output contains derivations that provide a development environment for `nix develop`.\n","name":"devShells","outputs":[{"outputs":[{"doc":null,"for_systems":["aarch64-darwin"],"path":["devShells","aarch64-darwin","default"],"short_description":"","store_paths":{"out":"/nix/store/2ywacj2bdm4fimi4dynb9pi19xxar4rc-purr-dev"},"what":"development environment"}],"platform":"aarch64-darwin"},{"outputs":[{"doc":null,"for_systems":["aarch64-linux"],"path":["devShells","aarch64-linux","default"],"short_description":"","store_paths":{"out":"/nix/store/y04m0gndvnpya73jv6sk4i8h77nz25lk-purr-dev"},"what":"development environment"}],"platform":"aarch64-linux"},{"outputs":[{"doc":null,"for_systems":["x86_64-linux"],"path":["devShells","x86_64-linux","default"],"short_description":"","store_paths":{"out":"/nix/store/cl5sknsp01rxjsl9z4jls1dmvj4s1zan-purr-dev"},"what":"development environment"}],"platform":"x86_64-linux"}]}},"pretty_download_url":"https://flakehub.com/f/nixcafe/purr/0.1.73.tar.gz","project":"purr","readme":"

Purr

\n

Purr — a lean Nix flake library for module auto-discovery and namespace\nsupport. Compared to other flake module auto-discovery tools, Purr stays\nminimal with a single dependency and a smaller default surface area.

\n

Why Purr?

\n\n

Usage

\n

Standalone (mkFlake)

\n
{\n  inputs = {\n    nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n    purr.url = \"github:nixcafe/purr\";\n  };\n\n  outputs = inputs:\n    inputs.purr.lib.mkFlake {\n      inherit inputs;\n      src = ./.;\n      namespace = \"myproject\";\n      outputsBuilder = { pkgs, ... }: {\n        formatter = pkgs.nixfmt;\n      };\n    };\n}\n
\n

flake-parts

\n
{\n  inputs = {\n    nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n    flake-parts.url = \"github:hercules-ci/flake-parts\";\n    purr.url = \"github:nixcafe/purr\";\n    my-extra-modules.url = \"github:user/my-extra-modules\";\n  };\n\n  outputs = inputs:\n    inputs.flake-parts.lib.mkFlake { inherit inputs; } {\n      imports = [ inputs.purr.flakeModules.default ];\n      systems = [ \"x86_64-linux\" \"aarch64-linux\" \"aarch64-darwin\" ];\n      purr = {\n        enable = true;\n        src = ./.;\n        namespace = \"cattery\";\n        extraModules.nixos = [\n          inputs.my-extra-modules.nixosModules.default\n        ];\n      };\n    };\n}\n
\n

Directory Structure

\n

All directories are auto-detected under src:

\n
src/\n├── lib/                              # Project library (auto-detect: \"lib\")\n│   ├── default.nix                   #   import { lib, inputs, namespace }: returns attrset\n│   ├── keys/\n│   │   └── default.nix               #   nested → lib..keys\n│   └── utils/\n│       └── default.nix               #   nested → lib..utils\n│                                     #   flattenLib = true → lib.\n│\n├── modules/                          # NixOS/darwin/home modules\n│   ├── nixos/                        #   → nixosModules\n│   ├── darwin/                       #   → darwinModules\n│   ├── home/                         #   → homeModules\n│   └── shared/                       #   → merged into nixos + darwin\n│\n├── packages/                         # Per-system packages (auto-detect: \"packages\")\n│   ├── known-hosts/\n│   │   └── default.nix               #   → packages..known-hosts\n│   └── match-blocks/\n│       └── default.nix               #   → packages..match-blocks\n│\n├── shells/                           # Dev shells (auto-detect: \"shells\", \"devShells\")\n│   └── default/\n│       └── default.nix               #   → devShells..default\n│\n├── checks/                           # Per-system checks (auto-detect: \"checks\")\n│   └── pre-commit/\n│       └── default.nix               #   → checks..pre-commit\n│\n├── overlays/                         # Overlays (auto-detect: \"overlays\")\n│   └── custom/\n│       └── default.nix               #   → overlays.custom\n│\n├── templates/                        # Flake templates (auto-detect: \"templates\")\n│   └── rust/                         #   non-recursive by default\n│       └── default.nix               #   → templates.rust\n│\n└── apps/                             # Per-system apps (auto-detect: \"apps\")\n    └── serve/\n        └── default.nix               #   → apps..serve\n
\n

Module arguments

\n

Each auto-discovered module receives different arguments:

\n

| Directory | Arguments |\n|---|---|---|\n| lib/ | { lib, inputs, namespace } |\n| modules/ | { config, options, lib, pkgs, namespace, ... } |\n| packages/ | { inputs, system, namespace, lib, pkgs } |\n| shells/ | { inputs, system, namespace, lib, pkgs } |\n| checks/ | { inputs, system, namespace, lib, pkgs } |\n| apps/ | { inputs, system, namespace, lib, pkgs } |\n| overlays/ | final: prev: (Nix overlay convention) |\n| templates/ | { inputs, namespace, lib } |\n| systems/ | { config, options, lib, pkgs, purr, ... } |\n| homes/ | { config, options, lib, pkgs, purr, ... } |

\n
\n

Note: lib in packages/, shells/, checks/, and apps/ includes the\nproject's custom lib under lib.<namespace>.*, merged via purrLib.\nsystems/ and homes/ receive a purr attrset with metadata about the\ncurrent configuration context via specialArgs / extraSpecialArgs.

\n
\n

Module Discovery

\n

Place modules under modules/ and they're auto-discovered:

\n
modules/\n├── nixos/services/openssh/default.nix  → nixosModules.services.openssh\n├── darwin/system/defaults/default.nix  → darwinModules.system.defaults\n├── home/programs/git/default.nix       → homeModules.programs.git\n└── shared/users/default.nix            → nixos + darwin (shared)\n
\n

Each module receives namespace as a parameter:

\n
{ config, lib, namespace, ... }@args:\nlet\n  cfg = config.${namespace}.my-module;\nin\n{\n  options.${namespace}.my-module.enable = lib.mkEnableOption \"my module\";\n  config = lib.mkIf cfg.enable { ... };\n}\n
\n

Custom Lib

\n

Create a lib/ directory under src to share functions across all modules:

\n
# lib/default.nix\n{ lib, inputs, namespace }:\n{\n  keys = import ./keys.nix { inherit lib inputs namespace; };\n  utils = import ./utils.nix { inherit lib inputs namespace; };\n}\n
\n

Functions are accessible as lib.<namespace>.* in all modules, packages,\nshells, and checks. Subdirectories nest by default\n(lib.<namespace>.keys.foo). Set flattenLib = true to merge all\nsubmodules directly under the namespace (lib.<namespace>.foo).

\n
# packages/known-hosts/default.nix\n{ pkgs, lib, namespace, ... }:\nlet\n  inherit (lib.${namespace}) keys;\nin\npkgs.writeText \"known-hosts\" (keys.generate { ... })\n
\n

The lib/ directory supports both a root default.nix and recursive\nsubdirectory discovery via findModules — both can coexist.

\n

Custom module directories

\n
moduleTypes = {\n  nixos = [\"nixos\" \"shared\" \"container\" \"nixos-musl\"];\n};\n
\n

Extra modules from other flakes

\n
extraModules = {\n  nixos = [\n    inputs.cattery-modules.nixosModules.default\n    inputs.disko.nixosModules.default\n  ];\n};\n
\n

Default module bundle

\n

By default, sub-modules are exported individually. Enable bundleModules = true\nto auto-generate a default module that imports all sub-modules:

\n
{ imports = [ inputs.myflake.nixosModules.default ]; }\n
\n

Set bundleExtraModules = false to exclude extraModules from the default\nbundle (only auto-discovered modules will be included). If you define your own\ndefault module under modules/, the auto-generated bundle is skipped.

\n

Systems & Homes

\n

Purr auto-discovers NixOS/darwin systems, home-manager homes, and image formats\nusing the <arch>-<format>/<name> convention (compatible with\nSnowfall Lib).

\n

Directory structure

\n
src/\n├── systems/                          # auto-detect: \"systems\", \"hosts\"\n│   ├── x86_64-linux/\n│   │   ├── server/default.nix        # → nixosConfigurations.server\n│   │   └── laptop/default.nix        # → nixosConfigurations.laptop\n│   ├── x86_64-iso/\n│   │   └── server/default.nix        # → isoConfigurations.server\n│   ├── x86_64-do/\n│   │   └── server/default.nix        # → doConfigurations.server\n│   └── aarch64-darwin/\n│       └── macbook/default.nix       # → darwinConfigurations.macbook\n│\n├── homes/                            # auto-detect: \"homes\"\n│   ├── x86_64-linux/\n│   │   ├── alice@server/default.nix  # → homeConfigurations.\"alice@server\"\n│   │   └── bob@server/default.nix    # → homeConfigurations.\"bob@server\"\n│   └── aarch64-darwin/\n│       └── alice@macbook/default.nix # → homeConfigurations.\"alice@macbook\"\n│\n├── modules/\n├── lib/\n└── ...\n
\n

System output mapping

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Format in dir nameFlake output keyBuilder
linuxnixosConfigurations.<name>nixosSystem
darwindarwinConfigurations.<name>darwinSystem
iso, do, …<format>Configurations.<name>nixosSystem + image.variant
\n

Home auto-linking

\n

Homes named <user>@<host> are automatically injected into matching hosts.\nWhen home-manager (or homeManager) is available as an input, building nixosConfigurations.server\nwill include all homes with @server suffix:

\n
# homes/x86_64-linux/alice@server/default.nix\n{ pkgs, ... }: {\n  home.packages = [ pkgs.neovim ];\n  programs.git.enable = true;\n}\n
\n

The home is auto-configured via home-manager.users.alice in the host's NixOS\nconfig. No additional wiring needed.

\n

Image formats (nixos-generators replacement)

\n

nixos-generators was merged into nixpkgs (25.05+). Set image.variant in the\nsystem config to build images. Purr auto-detects format directories and adds\nthe variant:

\n
# systems/x86_64-iso/server/default.nix\n{ ... }: {\n  image.variant = \"iso\";  # implied, auto-set by Purr\n}\n
\n

purr Metadata

\n

Each system and home module receives a purr attrset with metadata about the\ncurrent configuration. This is passed via specialArgs (systems) and\nextraSpecialArgs (homes).

\n

System modules (specialArgs.purr):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldExampleDescription
name\"server\"System/host name
arch\"x86_64\"Architecture
format\"linux\"linux, darwin, iso, ...
archFormat\"x86_64-linux\"Full arch-format string
homes[{user=\"alice\";host=\"server\";}]Linked home configs
\n

Home modules (extraSpecialArgs.purr):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldExampleDescription
user\"alice\"Username
host\"server\"Host name
arch\"x86_64\"Architecture
format\"linux\"linux, darwin, ...
archFormat\"x86_64-linux\"Full arch-format string
\n

Example:

\n
# systems/x86_64-linux/server/default.nix\n{ config, pkgs, lib, purr, ... }:\n{\n  networking.hostName = purr.name;  # \"server\"\n  nixpkgs.hostPlatform = purr.arch; # \"x86_64\"\n}\n
\n

Auto-injection

\n

By default (autoInject = true), Purr auto-injects basic configuration using\nlib.mkDefault — user modules can always override:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ContextInjected config
System confignetworking.hostName = <purr.name>
Home config (linux)home.username, home.homeDirectory = \"/home/<user>\"
Home config (darwin)home.username, home.homeDirectory = \"/Users/<user>\"
\n

Disable with autoInject = false.

\n

Example usage

\n

mkFlake:

\n
inputs.purr.lib.mkFlake {\n  inherit inputs;\n  src = ./.;\n  systemsDir = \"systems\";   # or \"hosts\", or null to auto-detect\n  homesDir = \"homes\";\n}\n
\n

flake-parts:

\n
purr = {\n  enable = true;\n  src = ./.;\n  systemsDir = \"systems\";\n  homesDir = \"homes\";\n}\n
\n

API

\n

mkFlake

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ParameterTypeDefault
inputsattrsrequiredFlake inputs. Required: nixpkgs. Optional: home-manager (or homeManager) for home-manager support, nix-darwin (or darwin) for darwin support
srcpathrequiredProject root directory
namespacenullOr strnullModule option namespace, also used as lib key (lib.<namespace>)
libDirnullOr strnullLib directory (relative to src), auto-detects lib/
flattenLibboolfalseFlatten lib subdirectories into root (no dir nesting)
systemslist[\"x86_64-linux\" \"aarch64-linux\" \"aarch64-darwin\"]Systems to generate for
nixpkgsConfigattrs{}nixpkgs config (allowUnfree, etc.)
outputsBuilderfn({ pkgs, system, inputs, namespace, lib }: {})Per-system extra flake outputs (formatter, packages, etc.)
modulesDirstr\"modules\"Module directory name under src
moduleTypesattrs{nixos=[\"nixos\" \"shared\"]; ...}Subdirectory mapping per output
extraModulesattrs{}{nixos=[...]; darwin=[...]; home=[...]} — raw module injection
bundleModulesboolfalseBundle all modules into a default module
bundleExtraModulesbooltrueInclude extra modules in the default bundle
checksDirnullOr strnullauto-detects checks/
shellsDirnullOr strnullauto-detects shells/ then devShells/
overlaysDirnullOr strnullauto-detects overlays/
packagesDirnullOr strnullauto-detects packages/
appsDirnullOr strnullauto-detects apps/
templatesDirnullOr strnullauto-detects templates/
templatesRecursiveboolfalseWhether to scan templates/ recursively
systemsDirnullOr strnullauto-detects systems/ then hosts/
homesDirnullOr strnullauto-detects homes/
autoInjectbooltrueAuto-inject networking.hostName, home.username, etc.
\n

flake-parts Options

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OptionTypeDefault
purr.enableboolfalse
purr.srcpathrequiredProject root
purr.namespacenullOr strnull
purr.libDirnullOr strnullauto-detects lib/
purr.flattenLibboolfalseFlatten lib subdirectories into root
purr.modulesDirstr\"modules\"
purr.moduleTypesattrs{nixos=[\"nixos\" \"shared\"]; ...}
purr.checksDirnullOr strnullauto-detects checks/
purr.shellsDirnullOr strnullauto-detects shells/ then devShells/
purr.overlaysDirnullOr strnullauto-detects overlays/
purr.packagesDirnullOr strnullauto-detects packages/
purr.appsDirnullOr strnullauto-detects apps/
purr.templatesDirnullOr strnullauto-detects templates/
purr.templatesRecursiveboolfalseWhether to scan templates/ recursively
purr.extraModulesattrs{}{nixos=[...]; darwin=[...]; home=[...]}
purr.bundleModulesboolfalseBundle all modules into a default module
purr.bundleExtraModulesbooltrueInclude extra modules in the default bundle
purr.systemsDirnullOr strnullauto-detects systems/ then hosts/
purr.homesDirnullOr strnullauto-detects homes/
purr.nixpkgsConfigattrs{}nixpkgs config (allowUnfree, etc.)
purr.autoInjectbooltrueAuto-inject networking.hostName, home.username, etc.
\n
inputs.purr.lib.defaultSystems  # [\"x86_64-linux\" \"aarch64-linux\" \"aarch64-darwin\"]\ninputs.purr.lib.eachSystem [...]\ninputs.purr.lib.eachDefaultSystem\ninputs.purr.lib.collectModules  # flatten nested modules to a list\ninputs.purr.lib.loadModules     # recursively load .nix files from a dir\n
\n

License

\n

CC0 1.0 Universal

\n","repo_url":"https://github.com/nixcafe/purr","revision":"2e7e4d20a3e010180481ed79ea79a6510a41eaf5","simplified_version":"0.1.73","source_github_owner_repo_pair":"nixcafe/purr","source_subdirectory":null,"spdx_identifier":"CC0-1.0","version":"0.1.73+rev-2e7e4d20a3e010180481ed79ea79a6510a41eaf5","visibility":"public"}