nix-darwin

nix-darwin Configuration

Architecture

Three-layer system: darwin modules (system) → home-manager (user) → homebrew (GUI apps).

flake.nix                          # Thin orchestration layer
├── hosts/workstation/             # Unstable packages, full toolchain
│   ├── default.nix → modules/darwin/
│   ├── home.nix    → modules/home-manager/base.nix + program modules
│   └── homebrew.nix → modules/homebrew/base.nix + host casks
└── hosts/homelab/                 # Stable packages (macOS 13), minimal
    ├── default.nix → modules/darwin/
    ├── darwin.nix                  # Host-specific overrides (mkForce)
    ├── home.nix    → modules/home-manager/base.nix + neovim-stable
    └── homebrew.nix

For full dependency flow and module layers, see references/architecture.md.

Core Conventions

Program Toggle Pattern

Every program module follows this structure (see templates/program-module.nix):

options.my.{program}.enable = mkEnableOption "description";
config = mkIf cfg.enable { /* config */ };

Enable in host's home.nix:

my.neovim.enable = true;

Adding a New Program

1. Create modules/home-manager/programs/{name}.nix using template
2. Import it in the host's home.nix
3. Set my.{name}.enable = true
4. If it needs a GUI cask, add to hosts/{host}/homebrew.nix

Configuration Management

Method	When to Use	Example
mkOutOfStoreSymlink	Config that changes without rebuild	nvim, aerospace
builtins.readFile	Config loaded into nix store	zed-editor
Inline nix	Simple, nix-native config	ghostty, starship

Naming Conventions

• Nix files: kebab-case.nix
• Module options: my.{program}.enable
• Dotfile symlinks: {name}.symlink in symlink/
• Hosts: kebab-case
• Commits: conventional (feat(neovim):, fix(darwin):)

Essential Commands

See references/commands.md for full list.

# Apply configuration
sudo nix run nix-darwin/master#darwin-rebuild -- switch --flake .#workstation
sudo nix run nix-darwin/master#darwin-rebuild -- switch --flake .#homelab

# Validate without applying
nix flake check

# Update inputs
nix flake update