API Reference¶

Complete reference for every function exported by nix-wire.

mkFlake¶

File: lib/default.nix (exported as inputs.nix-wire.mkFlake)

The main entry point. Wraps flake-parts.lib.mkFlake with auto-wiring logic for hosts, modules, packages, overlays, templates, and devshells.

Signature¶

mkFlake
  { inputs
  , prefix ? inputs.self
  , systems ? [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ]
  , packages ? "packages"
  , devShells ? "devShells"
  , hosts ? "hosts"
  , iso ? "${hosts}/iso"
  , templates ? "templates"
  , home ? true
  , imports ? [ ]
  , ...
  } -> flake outputs

Parameters¶

Parameter	Type	Default	Description
`inputs`	attrset	(required)	Your flake inputs. Must include `nixpkgs`, `flake-parts`, and (if `home = true`) `home-manager`. `nix-darwin` is required if you have Darwin hosts.
`prefix`	path	`inputs.self`	Base path for directory scanning. All directory paths are resolved as `${prefix}/${dir}`.
`systems`	list of strings	`["x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin"]`	Systems supported by the flake.
`packages`	string	`"packages"`	Directory name (relative to `prefix`) for package definitions.
`devShells`	string	`"devShells"`	Directory name (relative to `prefix`) for devshell definitions.
`hosts`	string	`"hosts"`	Directory name (relative to `prefix`) for host configurations.
`iso`	string	`"${hosts}/iso"`	Directory name (relative to `prefix`) for ISO configurations. Defaults to `hosts/iso`.
`templates`	string	`"templates"`	Directory name (relative to `prefix`) for flake templates.
`home`	bool	`true`	Whether to enable Home Manager integration for hosts. When `true`, `home-manager` must be in `inputs`.
`imports`	list	`[]`	Additional flake-parts modules to import.

Generated flake attributes¶

Attribute	Source	Generated by
`nixosConfigurations`	`${prefix}/${hosts}/nixos/`	`mkNixosConfigs`
`darwinConfigurations`	`${prefix}/${hosts}/darwin/`	`mkDarwinConfigs`
`darwinModules`	`${prefix}/modules/darwin/`	`wireModules`
`nixosModules`	`${prefix}/modules/nixos/`	`wireModules`
`homeModules`	`${prefix}/modules/home/`	`wireModules`
`flakeModules`	`${prefix}/modules/flake/`	`wireModules`
`overlays`	`${prefix}/overlays/`	`wireOverlays`
`templates`	`${prefix}/${templates}/`	`wireTemplates`
`packages.<system>`	`${prefix}/${packages}/` + `${prefix}/${iso}/`	`wirePackages` + `mkIsoPackages`
`devShells.<system>`	`${prefix}/${devShells}/`	`wirePackages`
`legacyPackages.<system>.homeConfigurations`	`${prefix}/${hosts}/home/`	`mkHomeConfigs`

Additionally, perSystem sets up pkgs with:

config.allowUnfree = true
overlays = attrValues inputs.self.overlays

Example¶

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
    flake-parts.url = "github:hercules-ci/flake-parts";
    home-manager.url = "github:nix-community/home-manager";
    home-manager.inputs.nixpkgs.follows = "nixpkgs";
    nix-darwin.url = "github:LnL7/nix-darwin";
    nix-darwin.inputs.nixpkgs.follows = "nixpkgs";
    nix-wire.url = "github:semi710/nix-wire";
  };

  outputs = inputs: inputs.nix-wire.mkFlake {
    inherit inputs;
    systems = [ "x86_64-linux" "aarch64-linux" ];
  };
}

Example with custom directories and flake-parts modules¶

outputs = inputs: inputs.nix-wire.mkFlake {
  inherit inputs;
  hosts = "machines";       # Use machines/ instead of hosts/
  packages = "pkgs";        # Use pkgs/ instead of packages/
  imports = [
    ./flake-parts/pre-commit.nix
    ./flake-parts/treefmt.nix
  ];
};

autoImport¶

File: lib/utils.nix (exported as inputs.nix-wire.lib.autoImport)

Imports all sibling .nix files and directories with default.nix from a given directory. Returns a list of paths suitable for use in imports.

Uses pure builtins only - works in any evaluation context (flakes, modules, repl, nix eval).

Signature¶

autoImport : path -> [path]

Parameters¶

Parameter	Type	Description
`dir`	path	Directory to scan for sibling `.nix` files and directories with `default.nix`

Returns¶

A list of paths. For each entry in the directory:

foo.nix → dir/foo.nix
foo/default.nix → dir/foo (the directory path)

Skips:

default.nix itself
Non-.nix regular files
Directories without default.nix

Behavior¶

If both foo.nix and foo/default.nix exist, both are included in the list (unlike wireGeneric which prefers the directory). This is because autoImport returns paths for imports lists where you typically want everything. If you need directory preference, use autoImportExcept to exclude the file.

Difference from wireGeneric

autoImport does not apply the filterPreferDir precedence rule. It's a simpler, pure-builtins function. wireGeneric (used internally by mkFlake) does apply precedence.

Example¶

# Directory structure:
# modules/
# ├── a.nix
# ├── b/
# │   └── default.nix
# └── default.nix

{ inputs, ... }:
{
  imports = inputs.nix-wire.lib.autoImport ./.;
  # Result: [ ./a.nix ./b ]
  # default.nix is skipped
}

autoImportExcept¶

File: lib/utils.nix (exported as inputs.nix-wire.lib.autoImportExcept)

Same as autoImport but also skips additional files/directories by name.

Signature¶

autoImportExcept : path -> [string] -> [path]

Parameters¶

Parameter	Type	Description
`dir`	path	Directory to scan
`exclusions`	list of strings	Names to exclude (in addition to `default.nix`)

Returns¶

A list of paths, same as autoImport, but excluding any entry whose name matches the exclusions list.

Example¶

# Directory structure:
# modules/
# ├── a.nix
# ├── b.nix
# ├── c.nix
# └── default.nix

{ inputs, ... }:
{
  imports = inputs.nix-wire.lib.autoImportExcept ./. [ "b.nix" "c.nix" ];
  # Result: [ ./a.nix ]
  # default.nix and b.nix and c.nix are skipped
}

# Exclude a directory
{ inputs, ... }:
{
  imports = inputs.nix-wire.lib.autoImportExcept ./. [ "experimental" ];
  # If experimental/default.nix exists, it's skipped
}

wireGeneric¶

File: lib/utils.nix (internal, not directly exported)

The generic directory walker. Scans a directory and builds an attribute set from .nix files and directories with default.nix. All other auto-wiring functions are specializations of this.

Signature¶

wireGeneric : { dir : path, buildFn : path -> string -> a, isDirAccepted : string -> string -> path -> bool } -> { ${name} : a }

Parameters¶

Parameter	Type	Default	Description
`dir`	path	(required)	Directory to scan
`buildFn`	`path -> string -> a`	(required)	Function applied to each entry. Receives `(path, name)` where `path` is the file path (or directory path) and `name` is the entry name (without `.nix`).
`isDirAccepted`	`string -> string -> path -> bool`	`isDirWithDefault`	Predicate to decide if a directory entry should be accepted. Default accepts directories containing `default.nix`.

Returns¶

An attribute set mapping entry names to buildFn results:

{
  foo = buildFn (dir + "/foo.nix") "foo";           # if foo.nix exists
  bar = buildFn (dir + "/bar") "bar";                # if bar/default.nix exists
}

Precedence rule¶

If both foo.nix and foo/default.nix exist, foo.nix is filtered out by filterPreferDir and only foo/default.nix is used.

Internal helpers used¶

Function	Description
`files dir`	Reads directory safely; returns `{}` if it doesn't exist
`filterPreferDir dir fs`	Filters out `foo.nix` when `foo/default.nix` exists
`isNixFile name type`	`type == "regular" && hasSuffix ".nix" name`
`isDirWithDefault name type dir`	`type == "directory" && pathExists (dir/name/default.nix)`
`stripNix name`	`removeSuffix ".nix" name`

Example (conceptual)¶

wireGeneric {
  dir = ./packages;
  buildFn = path: name: pkgs.callPackage path {};
  # Returns: { foo = callPackage ./packages/foo {}; bar = callPackage ./packages/bar {}; }
}

mkNixosConfigs¶

File: lib/utils.nix

Scans a directory for NixOS host configurations and wraps each with nixpkgs.lib.nixosSystem.

Signature¶

mkNixosConfigs : { dir : path, home : bool } -> { ${hostname} : nixosSystem }

Parameters¶

Parameter	Type	Description
`dir`	path	Directory containing NixOS host configs (e.g., `hosts/nixos/`)
`home`	bool	Whether to include Home Manager integration

Returns¶

An attribute set of NixOS configurations, one per host:

{
  laptop = nixpkgs.lib.nixosSystem { ... };
  workstation = nixpkgs.lib.nixosSystem { ... };
}

What each host gets¶

Every host configuration includes:

The host's own config - the .nix file or default.nix
User discovery - users.users.<name> from users/ subdirectory
Home Manager (if home = true) - full HM integration with per-user configs
Common Nix settings - allowUnfree, experimental-features, max-jobs
Hostname - networking.hostName = mkDefault <hostname>
Special args - { inputs, flake } available in all modules

Example¶

# Directory:
# hosts/nixos/
# ├── laptop.nix
# └── workstation/
#     ├── default.nix
#     └── users/
#         └── bob.nix

# Result:
# nixosConfigurations.laptop     = nixosSystem { modules = [ laptop.nix ... ]; }
# nixosConfigurations.workstation = nixosSystem { modules = [ workstation/default.nix ... ]; }

mkDarwinConfigs¶

File: lib/utils.nix

Scans a directory for macOS (nix-darwin) host configurations and wraps each with nix-darwin.lib.darwinSystem.

Signature¶

mkDarwinConfigs : { dir : path, home : bool } -> { ${hostname} : darwinSystem }

Parameters¶

Parameter	Type	Description
`dir`	path	Directory containing Darwin host configs (e.g., `hosts/darwin/`)
`home`	bool	Whether to include Home Manager integration

Returns¶

An attribute set of Darwin configurations, one per host.

What each host gets¶

Same as mkNixosConfigs but:

Uses nix-darwin.lib.darwinSystem instead of nixpkgs.lib.nixosSystem
Uses home-manager.darwinModules.home-manager instead of the NixOS variant
Adds Darwin-specific sessionPath in sharedModules:
/etc/profiles/per-user/$USER/bin (home-manager binaries)
/nix/var/nix/profiles/system/sw/bin (nix-darwin binaries)
/usr/local/bin (macOS GUI programs)

Example¶

# Directory:
# hosts/darwin/
# ├── macbook/
# │   ├── default.nix
# │   └── users/
# │       ├── carol/
# │       │   └── default.nix
# │       └── dave.nix
# └── office-mac.nix

# Result:
# darwinConfigurations.macbook    = darwinSystem { modules = [ macbook/default.nix ... ]; }
# darwinConfigurations.office-mac = darwinSystem { modules = [ office-mac.nix ... ]; }

mkIsoPackages¶

File: lib/utils.nix

Builds NixOS ISO image derivations as per-system packages. Arch-aware - only evaluates on Linux systems.

Signature¶

mkIsoPackages
  : { dir : path
    , home ? true
    , system : string
    , installerModule ? "installation-cd-minimal.nix"
    } -> { ${name} : derivation }

Parameters¶

Parameter	Type	Default	Description
`dir`	path	(required)	Directory containing ISO host configs (e.g., `hosts/iso/`)
`home`	bool	`true`	Whether to include Home Manager integration
`system`	string	(required)	The system to build for (e.g., `"x86_64-linux"`)
`installerModule`	string	`"installation-cd-minimal.nix"`	NixOS installer profile from `modulesPath`

Returns¶

An attribute set of ISO image derivations. Only populated for Linux systems (lib.hasSuffix "-linux" system). Returns {} for Darwin.

How it works¶

For each ISO host:

Evaluates a full NixOS system with nixpkgs.lib.nixosSystem
Imports the installer profile (e.g., installation-cd-minimal.nix)
Extracts eval.config.system.build.isoImage as the package
Attaches the full config as passthru.config for inspection

Example¶

# Directory:
# hosts/iso/
# └── rescue/
#     ├── default.nix
#     └── users/
#         └── nixos.nix

# Build:
# nix build .#rescue                          # Native-arch ISO
# nix eval .#packages.x86_64-linux.rescue \
#   --apply 'x: x.passthru.config.networking.hostName'

Custom installer profile¶

The installerModule defaults to installation-cd-minimal.nix. Other profiles from nixpkgs' modulesPath/installer/cd-dvd/ include:

installation-cd-minimal-new-kernel.nix
installation-cd-graphical.nix
installation-cd-graphical-calamares.nix

Architecture handling

ISOs are NixOS-specific. Darwin builds are automatically skipped. nix build .#rescue on an x86_64-linux machine produces an x86_64 ISO; on aarch64-linux it produces an aarch64 ISO.

mkHomeConfigs¶

File: lib/utils.nix

Scans a directory for standalone Home Manager configurations - users not tied to a specific host.

Signature¶

mkHomeConfigs : { dir : path, pkgs : nixpkgs } -> { ${username} : homeManagerConfiguration }

Parameters¶

Parameter	Type	Description
`dir`	path	Directory containing standalone home configs (e.g., `hosts/home/`)
`pkgs`	nixpkgs instance	The nixpkgs instance for the current system

Returns¶

An attribute set of Home Manager configurations, one per user. These are placed in legacyPackages.<system>.homeConfigurations.

What each user gets¶

{
  username = homeManagerConfiguration {
    inherit pkgs;
    extraSpecialArgs = { inherit inputs; flake = inputs.self; };
    modules = [
      path                          # ← the user's config file
      {
        home.username = username;
        home.homeDirectory = "/Users/${username}"  # or /home/ on Linux
        nix.package = pkgs.nix;
      }
    ];
  };
}

Example¶

# Directory:
# hosts/home/
# └── alice.nix

# Result (in legacyPackages.x86_64-linux.homeConfigurations):
# alice = homeManagerConfiguration { modules = [ alice.nix ... ]; }

# Build a standalone home config
home-manager switch --flake .#alice

wirePackages¶

File: lib/utils.nix

Scans a directory and applies pkgs.callPackage to each entry. Used for both packages and devshells.

Signature¶

wirePackages : { pkgs : nixpkgs, dir : path, callFn ? pkgs.callPackage } -> { ${name} : derivation }

Parameters¶

Parameter	Type	Default	Description
`pkgs`	nixpkgs instance	(required)	The nixpkgs instance for `callPackage`
`dir`	path	(required)	Directory to scan
`callFn`	function	`pkgs.callPackage`	The call function to apply to each package

Returns¶

An attribute set of derivations:

{
  foo = pkgs.callPackage ./packages/foo {};
  bar = pkgs.callPackage ./packages/bar {};
}

Example¶

# packages/foo/default.nix
{ stdenv, ... }:
stdenv.mkDerivation {
  pname = "foo";
  version = "1.0.0";
  # ...
}

# Result: packages.x86_64-linux.foo = <derivation>
# nix build .#foo

wireModules¶

File: lib/utils.nix

Scans a directory and maps each entry name to its file path. Used for nixosModules, darwinModules, homeModules, and flakeModules.

Signature¶

wireModules : { dir : path } -> { ${name} : path }

Parameters¶

Parameter	Type	Description
`dir`	path	Directory to scan

Returns¶

An attribute set mapping module names to their paths:

{
  test = ./modules/nixos/test;       # if test/default.nix exists
  mymodule = ./modules/nixos/mymodule.nix;  # if mymodule.nix exists
}

Example¶

# modules/nixos/
# ├── test.nix
# └── mymodule/
#     └── default.nix

# Result: nixosModules = { test = ./modules/nixos/test.nix; mymodule = ./modules/nixos/mymodule; }

# Usage in a host:
{ flake, ... }: {
  imports = [ flake.nixosModules.test ];
}

wireOverlays¶

File: lib/utils.nix

Scans a directory and imports each overlay with special args.

Signature¶

wireOverlays : { dir : path } -> { ${name} : overlay }

Parameters¶

Parameter	Type	Description
`dir`	path	Directory containing overlay files

Returns¶

An attribute set of overlays. Each overlay is imported with { inherit inputs; flake = inputs.self; } as additional arguments.

How overlays receive args¶

# overlays/default.nix
{ inputs, flake, ... }:    # ← these come from commonSpecialArgs
final: prev: {
  myPackage = prev.myPackage.override { ... };
}

The overlay function receives commonSpecialArgs first, then returns the final: prev: overlay function.

Example¶

# overlays/my-overlay.nix
{ ... }:
final: prev: {
  hello = prev.hello.overrideAttrs (old: {
    patches = (old.patches or []) ++ [ ./fix.patch ];
  });
}

# Result: overlays.my-overlay = <overlay function>
# Automatically applied to all pkgs instances in the flake

wireTemplates¶

File: lib/utils.nix

Scans a directory and maps each subdirectory to a flake template.

Signature¶

wireTemplates : { dir : path } -> { ${name} : { path : path, description : string } }

Parameters¶

Parameter	Type	Description
`dir`	path	Directory containing template subdirectories

Returns¶

An attribute set of template objects:

{
  python-uv = {
    path = ./templates/python-uv;
    description = "Python project with uv and direnv";
  };
}

Template discovery¶

Uses a custom isDirAccepted that accepts any directory - no default.nix required. Each template directory can optionally contain a template.nix file with { description = "..."; } for custom metadata.

Example¶

templates/
└── python-uv/
    ├── .envrc
    ├── .gitignore
    ├── flake.nix
    └── template.nix      # { description = "Python project with uv"; }

# templates/python-uv/template.nix
{
  description = "Python project with uv and direnv";
}

# Use a template
nix flake init -t .#python-uv

Internal functions¶

These are used internally but not exported. Documented for understanding the architecture.

commonNix¶

commonNix = {
  nixpkgs.config.allowUnfree = mkDefault true;
  nixpkgs.overlays = attrValues inputs.self.overlays;
  nix.settings.max-jobs = mkDefault "auto";
  nix.settings.experimental-features = mkDefault "nix-command flakes";
};

Applied to every NixOS and Darwin host. All values are mkDefault - overridable in host config.

commonSpecialArgs¶

commonSpecialArgs = { inherit inputs; flake = inputs.self; };

Passed as specialArgs to every nixosSystem, darwinSystem, and as extraSpecialArgs to every Home Manager configuration.

commonModules¶

commonModules : "nixos" | "darwin" -> bool -> path -> path -> string -> [module]

Builds the shared module list for every host. Parameters:

Parameter	Description
`type`	`"nixos"` or `"darwin"`
`home`	Whether to include Home Manager modules
`path`	Path to the host's config file
`dir`	Base directory for host configs
`hostname`	Name of the host

commonHomeModules¶

commonHomeModules : "nixos" | "darwin" -> path -> string -> [module]

Extracts Home Manager modules for a host. Imports the appropriate HM module (nixosModules.home-manager or darwinModules.home-manager), sets defaults, and wires per-user configs via getUsersHome.

mkUsers¶

mkUsers : path -> string -> (path -> string -> a) -> { ${username} : a }

Generic user collector. Looks for a users/ subdirectory inside a host directory and walks it with wireGeneric.

getUsers¶

getUsers : path -> string -> nixpkgs -> { ${username} : { home = ...; } }

Creates users.users.<name> entries with default home paths: /Users/<name> on Darwin, /home/<name> on Linux.

getUsersHome¶

getUsersHome : path -> string -> { ${username} : { imports = [path]; } }

Creates home-manager.users.<name> entries that import each user's config file.

isoModules¶

isoModules : bool -> path -> path -> string -> string -> [module]

Shared module list for ISO hosts. Parameters: home, path, dir, hostname, installerModule. Combines commonModules with the NixOS installer profile import.

filterPreferDir¶

filterPreferDir : path -> attrset -> attrset

Filters out foo.nix when foo/default.nix exists in the same directory.

files¶

files : path -> attrset

Reads a directory safely. Returns {} if the directory doesn't exist.

isNixFile¶

isNixFile : string -> string -> bool

Checks if an entry is a regular .nix file.

isDirWithDefault¶

isDirWithDefault : string -> string -> path -> bool

Checks if an entry is a directory containing default.nix.

isDirWithTemplate¶

isDirWithTemplate : string -> string -> path -> bool

Checks if an entry is a directory containing template.nix.

stripNix¶

stripNix : string -> string

Removes the .nix suffix from a filename.