Nix Config

How the flake is wired

Module layering

Each configuration loads modules in order:

1. Common (cross-platform) — hosts/common (packages, fonts, users)
2. Platform — hosts/darwin or hosts/nixos
3. Layer (darwin only) — hosts/darwin/personal or hosts/darwin/work
4. Host — hosts/<platform>/<layer>/<host>

In flake.nix, this is expressed as:

commonModules = [ ./hosts/common ];

# Darwin host
sap = nix-darwin.lib.darwinSystem {
  modules = [
    ./hosts/common              # common
    ./hosts/darwin              # platform
    ./hosts/darwin/work         # layer
    ./hosts/darwin/work/sap     # host
  ];
  specialArgs = { inherit inputs; host = import ./hosts/darwin/work/sap/variables.nix; };
};

# NixOS host
homeserver = nixpkgs.lib.nixosSystem {
  modules = [
    ./hosts/common              # common
    ./hosts/nixos               # platform
    ./hosts/nixos/homeserver    # host
  ];
  specialArgs = { inherit inputs; host = import ./hosts/nixos/homeserver/variables.nix; };
};

Nix merges lists from all modules automatically — packages from each layer are combined, not replaced.

Host variables pattern

Each host has a variables.nix that exports a plain attribute set (not a module):

rec {
  username = "wagou";
  homeDir = "/Users/${username}";     # /home/${username} for NixOS
  restricted_app_dir = "/Applications"; # darwin only
  enableRosetta = false;                # darwin only
  hostname = "homeserver";              # NixOS only
}

These are passed via specialArgs and available in all modules as { host, ... }:.

Adding packages

Cross-platform CLI tool (all machines)

Edit hosts/common/packages.nix:

environment.systemPackages = with pkgs; [ ... new-package ... ];

Darwin-only CLI tool

Edit hosts/darwin/packages.nix.

Layer-specific or host-specific

Edit the appropriate packages.nix under hosts/darwin/<layer>/ or hosts/darwin/<layer>/<host>/.

Homebrew cask (GUI app)

Edit the appropriate homebrew.nix and add to the casks list. For custom install path: { name = "app"; args = { appdir = host.restricted_app_dir; }; }

Homebrew brew (CLI formula)

Edit the appropriate homebrew.nix and add to the brews list.

Mac App Store app

Add to masApps in the appropriate homebrew.nix:

masApps = { "App Name" = 123456789; };

Adding a new darwin host

1. Choose the layer (personal or work)
2. Create hosts/darwin/<layer>/<hostname>/variables.nix:

   rec {
     username = "myuser";
     homeDir = "/Users/${username}";
     restricted_app_dir = "/Applications";
     enableRosetta = false;
   }
   

3. Create hosts/darwin/<layer>/<hostname>/default.nix:

   _: { }
   

4. Add a darwinConfigurations.<hostname> entry in flake.nix:

   <hostname> = nix-darwin.lib.darwinSystem {
     system = "aarch64-darwin";
     modules = commonModules ++ [
       ./hosts/darwin
       ./hosts/darwin/<layer>
       ./hosts/darwin/<layer>/<hostname>
     ];
     specialArgs = {
       inherit inputs;
       host = import ./hosts/darwin/<layer>/<hostname>/variables.nix;
     };
   };
   

Adding a new NixOS host

1. Create hosts/nixos/<hostname>/variables.nix:

   rec {
     username = "myuser";
     homeDir = "/home/${username}";
     hostname = "<hostname>";
   }
   

2. Create hosts/nixos/<hostname>/default.nix with imports for hardware and services
3. Create hosts/nixos/<hostname>/hardware.nix (from nixos-generate-config on the target machine)
4. Create hosts/nixos/<hostname>/services.nix for host-specific services
5. Add a nixosConfigurations.<hostname> entry in flake.nix

Adding macOS settings

1. Create hosts/darwin/settings/<category>.nix:

   _: {
     system.defaults.<namespace> = {
       option = value;
     };
   }
   

2. Add it to the imports in hosts/darwin/settings/default.nix

Common system.defaults namespaces: dock, finder, NSGlobalDomain, trackpad, CustomUserPreferences, menuExtraClock, screencapture, screensaver, spaces, controlcenter, magicmouse, SoftwareUpdate.

Adding custom icons

1. Place .icns file in hosts/darwin/icons/
2. Add an entry in hosts/darwin/icons.nix:

   { path = "/Applications/AppName.app"; icon = ./icons/appname.icns; }
   

Adding a Homebrew tap

1. Add the tap as a flake input in flake.nix:

   homebrew-newtap = { url = "github:owner/homebrew-repo"; flake = false; };
   

2. Register it in nix-homebrew.taps in the appropriate homebrew.nix:

   nix-homebrew.taps = { "owner/homebrew-repo" = inputs.homebrew-newtap; };
   

Nix language essentials

# Attribute set
{ key = "value"; nested = { a = 1; }; }

# List
[ "one" "two" "three" ]

# with expression (bring attrs into scope)
environment.systemPackages = with pkgs; [ git vim tmux ];

# String interpolation
home = "${host.homeDir}/Downloads";

# rec — self-referencing attrset
rec { username = "me"; homeDir = "/Users/${username}"; }

# inherit — shorthand for x = x
specialArgs = { inherit inputs; };

# Function with destructured attrset argument
{ pkgs, lib, ... }:
{
  # module body
}

# Unused arguments
_: { }

Module system

• Modules are functions that return attribute sets of option values
• Multiple modules setting the same list option are merged (e.g., environment.systemPackages)
• Multiple modules setting the same scalar option will conflict
• Use lib.mkForce to override, lib.mkDefault for low-priority defaults
• Use lib.mkIf <condition> { ... } for conditional configuration

Development workflow

Pre-commit hooks (git-hooks.nix)

Hooks auto-install when entering the dev shell. On every commit:

• nixfmt — formatting check
• statix — lint for anti-patterns
• deadnix — find unused code

Full builds are verified by CI after push.

Dev shell

nix develop          # manual entry
# or just cd into the repo — mise auto-activates via .mise.toml

Flake checks

nix flake check      # runs all checks + builds

CI (GitHub Actions)

• lint — nixfmt, statix, deadnix (macos-15)
• build-darwin — sap, wagou, pro (macos-15, parallel)
• build-nixos — homeserver (ubuntu-latest)

Key commands

Important rules

• ALWAYS work in ~/.config/wagounix/ — this is the source of truth
• Use build first to test, then switch to activate
• When adding a package, check if it exists: nix search nixpkgs <name>
• GUI apps → Homebrew casks; CLI tools → nix packages (prefer nix when available)
• onActivation.cleanup = "uninstall" — removing a cask/brew from config WILL uninstall it
• mutableTaps = false — add new taps as flake inputs
• No home-manager — user dotfiles are managed by chezmoi separately
• macOS: Nix daemon is managed by Lix installer (nix.enable = false in darwin config)
• NixOS: system.stateVersion must match the version at install time — never change it
• NixOS: hardware.nix is auto-generated — replace placeholder with real one from the server
• Commit and push after successful rebuilds