Nix Module Platform-Specific Options

Overview

When writing Nix modules that need to hide platform-specific options (NixOS vs Darwin), using mkIf alone causes infinite recursion. This skill documents the correct pattern.

The Problem

mkIf is evaluated lazily but the option path is still visible during module evaluation. This causes errors like:

code

error: The option `users.defaultUserShell' does not exist.

Or infinite recursion when config is referenced in option defaults or optionalAttrs conditions.

The Pattern

Use optionalAttrs for platform checks, mkIf for config-dependent checks.

Check Type	Tool	Evaluated
Platform (`isDarwin`, `!isDarwin`)	`optionalAttrs`	Parse time
Config values (`cfg.enable`, `cfg.flavor`)	`mkIf`	Lazy

Examples

❌ Wrong: mkIf for platform check

nix

config = mkIf (!isDarwin) {
  users.defaultUserShell = pkgs.zsh;  # Darwin sees this path!
};

✅ Correct: optionalAttrs for platform check

nix

config = optionalAttrs (!isDarwin) {
  users.defaultUserShell = pkgs.zsh;  # Hidden from Darwin
};

❌ Wrong: Config value in optionalAttrs condition

nix

# cfg.flavor evaluated at parse time → infinite recursion
(optionalAttrs (isDarwin && cfg.flavor == "personal") {
  services.onepassword-secrets.enable = true;
})

✅ Correct: Nest mkIf inside optionalAttrs

nix

# Platform check at parse time, config check lazy
(optionalAttrs isDarwin (mkIf (cfg.flavor == "personal") {
  services.onepassword-secrets.enable = true;
}))

❌ Wrong: config reference in option default

nix

options.modules.foo = {
  user = mkOpt types.str config.user.name;  # Infinite recursion!
};

✅ Correct: Static default, use config in config section

nix

options.modules.foo = {
  user = mkOpt types.str null;
};

config = mkIf cfg.enable (let
  user = if cfg.user != null then cfg.user else config.user.name;
in {
  # Use 'user' variable here
});

Combined Pattern

For modules with both platform-specific options AND config-dependent behavior:

nix

config = mkIf cfg.enable (mkMerge [
  # Common config (all platforms)
  { /* ... */ }

  # Darwin-only options
  (optionalAttrs isDarwin {
    programs.zsh.interactiveShellInit = "...";
  })

  # NixOS-only options
  (optionalAttrs (!isDarwin) {
    users.defaultUserShell = pkgs.zsh;
  })

  # Darwin + config-dependent (nested)
  (optionalAttrs isDarwin (mkIf (cfg.flavor == "personal") {
    services.onepassword-secrets.enable = true;
  }))
]);

Quick Reference

Scenario	Pattern
NixOS-only option	`optionalAttrs (!isDarwin) { ... }`
Darwin-only option	`optionalAttrs isDarwin { ... }`
Platform + enable check	`optionalAttrs isDarwin (mkIf cfg.enable { ... })`
Platform + config value	`optionalAttrs isDarwin (mkIf (cfg.foo == "bar") { ... })`
Option default from config	Use `null` default, resolve in `config` section

Debugging

When you see infinite recursion errors mentioning _module.freeformType or anon-43:

•Search for config. references in option defaults
•Search for cfg. references in optionalAttrs conditions
•Search for mkIf (!isDarwin) or mkIf isDarwin guarding platform-specific options

bash

# Find problematic patterns
grep -rn "mkOpt.*config\." modules/
grep -rn "optionalAttrs.*cfg\." modules/
grep -rn "mkIf.*isDarwin" modules/