nix-darwin Configuration

Two hosts (workstation, homelab) are built by mkDarwinConfig in flake.nix from three layers: darwin modules (system) → home-manager (user) → nix-homebrew (GUI apps and taps). Both hosts share nixpkgs-unstable. Read the host's home.nix and homebrew.nix for what is currently enabled; do not rely on remembered program lists.

Conventions

New programs follow templates/program-module.md: an options.my.<program>.enable module under modules/home-manager/programs/, imported by the host's home.nix and enabled there. Shared programs are imported by modules/home-manager/base.nix instead.

Config delivery	When to use	Example
mkOutOfStoreSymlink	Config edited often, applied without rebuild	neovim, aerospace
builtins.readFile	Config copied into the Nix store	zed-editor
Inline Nix settings	Small, Nix-native config	ghostty, starship

Naming: kebab-case.nix files and host names, my.<program>.enable options, symlink/<name>.symlink dotfiles, and conventional commit scopes such as feat(neovim): or fix(darwin):.

Read by problem

Problem or decision	Reference
Where a module is wired in, or why the layout is shaped this way	architecture.md
Build, rollback, generations, input updates, garbage collection	commands.md
darwin-rebuild or evaluation failure, Homebrew DSL or tap errors, macOS compatibility	gotchas.md
The user asks how to restructure or improve the configuration	community-patterns.md — check each pattern's status in this repo first

Complete the change

Evaluate each affected host with nix eval --raw .#darwinConfigurations.<host>.system.drvPath. nix flake check only checks formatting and passes even when a host fails to evaluate; nix fmt fixes formatting. Changes under modules/, hosts/, or flake.nix take effect only after darwin-rebuild switch; follow the project CLAUDE.md for when that needs confirmation.