{"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.106+rev-4f5ea66ed5b00f4471bbc9a63f7903dcc563d218.tar.gz","labels":["module-system","flake-framework","flake-parts","auto-discovery","nix","nix-flake"],"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/6111v5plnpi3p4zk7gg3bdm5m8shcl8p-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/29wz64hn7ziqmq781ajw1k7bazs53z7i-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/4xkg5f3if9yrgwwyswxxagazjbdkp47c-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/qi1rsyacjdfwxp15gzdp6ni6mli7a2n2-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/jg9adjrpy3wwjppyg9ygkb1p8zjz9n9m-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/5zvxy03v24znvchdkrzlv2799c8jxsq8-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/8hs8n8kjcc77z981y0bzy9n2ymn3g0ip-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/fpq7gimhcjk27a8n40flr2gjswnm0max-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/nn65rglxav0wxpxdplrdfdjpa38zzxxh-purr-dev"},"what":"development environment"}],"platform":"x86_64-linux"}]},"templates":{"doc":"The `templates` output provides project templates.\n","name":"templates","outputs":[{"outputs":[{"doc":null,"for_systems":[null],"path":["templates","default"],"short_description":"A minimal flake using purr standalone (mkFlake).\n","store_paths":{},"what":"template"},{"doc":null,"for_systems":[null],"path":["templates","flake-parts"],"short_description":"A minimal flake using purr with flake-parts.\n","store_paths":{},"what":"template"}],"platform":null}]}},"pretty_download_url":"https://flakehub.com/f/nixcafe/purr/0.1.106.tar.gz","project":"purr","readme":"

purr

\n

\n A lean Nix flake framework — auto-discovery, namespaces, and module composition.\n
\n purr.nixcafe.org\n

\n

\n \"FlakeHub\"\n \"License\"\n

\n
\n

What is purr?

\n

purr turns your project directory structure into a fully wired Nix flake — no boilerplate, no manual wiring. Drop files into conventional directories and purr discovers everything: modules, packages, shells, checks, apps, overlays, templates, NixOS/darwin systems, home-manager homes, and a shared lib.

\n

Compared to other flake auto-discovery tools, purr stays minimal — a single dependency (nixpkgs-lib, ~2 MB) and a small, focused API surface.

\n
# flake.nix — that's it. No manual wiring needed.\n{\n  inputs = {\n    nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n    purr.url = \"https://flakehub.com/f/nixcafe/purr/0.1.*.tar.gz\";\n  };\n\n  outputs = inputs:\n    inputs.purr.lib.mkFlake {\n      inherit inputs;\n      src = ./.;\n    };\n}\n
\n

Put your code in the right directories, and purr wires your entire flake:

\n
.\n├── flake.nix\n├── modules/              → nixosModules, darwinModules, homeModules\n├── packages/             → packages..*\n├── legacyPackages/       → legacyPackages..*\n├── shells/               → devShells..*\n├── checks/               → checks..*\n├── apps/                 → apps..*\n├── overlays/             → overlays.*\n├── templates/            → templates.*\n├── formatters/           → formatter.\n├── hydraJobs/            → hydraJobs.* (CI jobs, opt-in)\n├── lib/                  → lib..* (shared across all modules)\n├── systems/              → nixosConfigurations, darwinConfigurations\n└── homes/                → homeConfigurations\n
\n

Quick Start

\n

Scaffold a new purr project in seconds:

\n
# Standalone (mkFlake)\nnix flake init -t github:nixcafe/purr\n\n# With flake-parts\nnix flake init -t github:nixcafe/purr#flake-parts\n
\n

Usage

\n

purr offers two integration modes — pick the one that fits your workflow.

\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 module

\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  };\n\n  outputs = inputs:\n    inputs.flake-parts.lib.mkFlake { inherit inputs; } {\n      imports = [ inputs.purr.flakeModules.default ];\n      purr = {\n        enable = true;\n        src = ./.;\n        namespace = \"myproject\";\n      };\n    };\n}\n
\n

Core Concepts

\n

Automatic Module Discovery

\n

Drop modules into modules/ — purr discovers them by subdirectory convention:

\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            → merged into nixos + darwin\n
\n

Customize the mapping with moduleTypes:

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

Namespace Support

\n

purr injects a namespace parameter into every module, scoping options under config.<namespace>.* — no more global option collisions:

\n
{ config, lib, namespace, ... }:\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 (lib.<namespace>.*)

\n

Create a lib/ directory to share functions across all modules, packages, shells, and checks:

\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

Access anywhere with lib.<namespace>.keys, lib.<namespace>.utils, etc.

\n

Systems & Homes

\n

purr auto-discovers NixOS/darwin systems and home-manager homes using <arch>-<format>/<name>:

\n
systems/\n├── x86_64-linux/server/default.nix    → nixosConfigurations.server\n└── aarch64-darwin/macbook/default.nix → darwinConfigurations.macbook\n\nhomes/\n└── x86_64-linux/alice@server/default.nix  → homeConfigurations.\"alice@server\"\n
\n

Each host can carry host meta — a meta.nix next to its default.nix, or hosts.<name>.meta in the flake config. Declaring images in the meta makes the host an image-only recipe (e.g. installer ISOs): it is excluded from nixosConfigurations/darwinConfigurations unless you also set deployable = true. Its images are exposed as a top-level images.<host>.<format> output:

\n
# systems/x86_64-linux/installer/meta.nix\n{\n  images = [ \"iso\" ];\n}\n
\n

The merged meta (auto-generated keys + your custom keys) is injected into the host's modules as purr.meta.

\n

Homes named <user>@<host> auto-link to matching hosts. No extra wiring needed.

\n
# systems/x86_64-linux/server/default.nix\n{ config, pkgs, lib, purr, ... }:\n{\n  networking.hostName = purr.meta.name;  # \"server\"\n  # ...auto-injects home-manager config for alice@server automatically\n}\n
\n

Namespace Bridge

\n

Forward home-manager config from any NixOS module via the namespace bridge — set purr.users.<name>.homeConfig on a host with linked homes:

\n
{ config, pkgs, lib, ... }:\n{\n  purr.users.alice.homeConfig = {\n    home.packages = [ pkgs.cowsay ];\n    programs.git.userName = \"Alice\";\n  };\n}\n
\n

Why 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
purrOther frameworks
Dependencies1 (nixpkgs-lib, ~2 MB)3+ (flake-parts, flake-utils, ...)
API surfaceSingle mkFlake call or one flake-parts moduleMultiple nested imports
Option namespaceBuilt-in namespace injectionManual config.<name>. prefixing
Systems & homesAuto-discovered, auto-linkedManual wiring
Custom liblib.<namespace>.* propagated everywhereManual import passthrough
\n

Testing

\n

Tests live under tests/ and are auto-discovered — drop a\ntest-*.nix into tests/unit/ (1:1 with a lib/ module) or\ntests/integration/ (real-project runs against tests/integration/project)\nand it is picked up automatically.

\n
nix flake check                       # CI gate: pre-commit + purr-tests\nnix build .#checks.x86_64-linux.purr-tests && cat result   # full per-test report\ntests/run-tests.sh                    # run directly, live per-test output\nnix develop --command purr-test       # same, from the dev shell\n
\n

The purr-tests check writes the full report into its result; if a test\nfails the build fails and nix log shows the failing cases. Unit tests run\nhermetically with nixpkgs-lib; integration tests mock nixosSystem /\nhomeManagerConfiguration to evaluate the generated configs through the real\nlib.evalModules without pulling a full nixpkgs.

\n

Documentation

\n

Full documentation at purr.nixcafe.org — flake-parts integration, full API reference, directory layout guide, and more.

\n

License

\n

CC0 1.0 Universal

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