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:

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

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

✅ Correct: optionalAttrs for platform check

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

❌ Wrong: Config value in optionalAttrs condition

cfg.flavor evaluated at parse time → infinite recursion

(optionalAttrs (isDarwin && cfg.flavor == "personal") { services.onepassword-secrets.enable = true; })

✅ Correct: Nest mkIf inside optionalAttrs

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

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

✅ Correct: Static default, use config in config section

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:

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

Find problematic patterns

grep -rn "mkOpt.*config." modules/ grep -rn "optionalAttrs.*cfg." modules/ grep -rn "mkIf.*isDarwin" modules/