Skip to content

Blueprint and Others

Overview

Blueprint (Numtide) is an opinionated flake library that maps a standard folder layout onto flake outputs. Drop files under packages/, hosts/, modules/, devshells/, and similar directories; Blueprint wires them to packages.*, nixosConfigurations.* / darwinConfigurations.*, nixosModules.*, devShells.*, and related attrs. The design goal is to cut glue code so flake.nix stays thin—closer to Rails-style convention than to a free-form outputs function.

Blueprint is one of several community scaffolds (upstream marks it experimental as of 2026-07). They share a problem (noisy flakes, ad-hoc repo layout) but differ in mechanism. flake-parts evaluates outputs through the Nix module system. Blueprint and peers such as Snowfall, Digga / Hive, and std / Paisano prefer fixed directory or cell conventions. Numtide positions Blueprint as a spiritual successor to flake-utils: keep mapping predictable (KISS, 1:1 paths → attrs), avoid deep module recursion, and break out when the project outgrows the scaffold.

Details

Blueprint mechanism

Add Blueprint as an input and hand outputs to it:

outputs = inputs: inputs.blueprint { inherit inputs; };

Optional prefix (often "nix/") nests the scanned tree under a subdirectory so Nix folders stay separate from application sources. Root special files such as devshell.nix, package.nix, and formatter.nix cover defaults; named entries live under the conventional directories (packages/foo/default.nix → packages.<system>.foo, and so on). Supported surfaces include NixOS, nix-darwin, Home Manager, system-manager, nix-unit, RFC 166 formatting via nix fmt, overridable systems via nix-systems, and automatic flake checks derived from packages, devshells, and NixOS configurations.

Upstream is explicit that Blueprint is not aimed at highly complex flakes: once conventions fight the problem, leave the scaffold and compose outputs yourself (or switch to a module-based approach).

Map: community frameworks vs flake-parts

Approach How structure is expressed Typical fit
Blueprint Fixed folders/files → flake attrs Small–medium repos; want almost no outputs boilerplate
flake-parts NixOS-style modules (imports, perSystem, options) Growing flakes; shareable flakeModules; flexible schema
Snowfall Opinionated lib + directory conventions (Snowfall Org) Homogeneous multi-host / multi-package trees in that ecosystem
Digga / Hive Digga (deprecated) / divnix Hive collectors Digga→Hive handoff; not Colmena hive or Clan mesh
std / Paisano Cells/blocks (divnix Standard / Paisano) Structured monorepos with std’s cell model
clan-core (related) Broader deployment/product stack Machines/deploy (+ Clan mesh VPN)—not a thin folder mapper

Rule of thumb: choose folder/convention scaffolds (Blueprint, Snowfall, std, …) when the team wants one obvious layout and low ceremony; choose flake-parts when you need mergeable options, reusable flake modules, and a closer fit to the raw flake schema without a mandatory directory tree.

Examples

Scaffold a new project:

mkdir my-project && cd my-project
nix flake init -t github:numtide/blueprint

Minimal flake.nix after init (inputs aside, outputs stay one call):

{
  description = "Simple flake with a devshell";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs?ref=nixos-unstable";
    blueprint.url = "github:numtide/blueprint";
    blueprint.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = inputs: inputs.blueprint { inherit inputs; };
}

With a nix/ prefix and a package folder nix/packages/hello/default.nix, build with nix build .#hello. Default developer env lives in root devshell.nix (or under devshells/ for multiple shells)—nix develop without stuffing a devShells attr into flake.nix by hand.

See also

References