nix

name	nix
description	Nix Best Practices

Nix Best Practices

Comprehensive guide for working with Nix, including flakes, NixOS, home-manager, nix-darwin, and development environments.

Core Principles

1. Use Flakes for Reproducibility

Always prefer flakes over channels for new projects. Flakes provide:

• Pinned dependencies via flake.lock
• Hermetic evaluation (no NIX_PATH dependencies)
• Standardized project structure
• Composable inputs and outputs

2. Enable Flakes

# In configuration.nix or nix.conf
nix.settings.experimental-features = [ "nix-command" "flakes" ];

3. Directory Structure (Snowfall-style Pattern)

nixos-config/
├── flake.nix           # Entry point
├── flake.lock          # Pinned dependencies
├── systems/            # Per-machine configs
│   ├── x86_64-linux/
│   │   └── hostname/default.nix
│   └── aarch64-darwin/
│       └── hostname/default.nix
├── modules/
│   ├── nixos/          # NixOS-specific modules
│   ├── darwin/         # macOS-specific modules
│   └── home/           # Home-manager (cross-platform)
├── homes/              # Per-user home-manager configs
├── packages/           # Custom packages
└── secrets/            # Encrypted secrets (sops-nix)

4. Configuration Layering

Configurations build up in layers, each can override the previous:

• Linux: flake.nix → systems → modules/nixos → modules/home
• macOS: flake.nix → systems → modules/darwin → modules/home

5. Avoid Common Anti-patterns

# BAD: Implicit scope with `with`
environment.systemPackages = with pkgs; [ git vim wget ];

# GOOD: Explicit references
environment.systemPackages = [ pkgs.git pkgs.vim pkgs.wget ];

# Or use a let binding
environment.systemPackages = let p = pkgs; in [ p.git p.vim p.wget ];

Essential Commands

# Build and switch NixOS configuration
sudo nixos-rebuild switch --flake .#hostname

# Build and switch nix-darwin
darwin-rebuild switch --flake .#hostname

# Build home-manager standalone
home-manager switch --flake .#user@hostname

# Update all flake inputs
nix flake update

# Update specific input
nix flake update nixpkgs

# Search packages
nix search nixpkgs packagename

# Enter development shell
nix develop

# Garbage collection (with generation cleanup)
sudo nix-collect-garbage -d --delete-older-than 7d

# Show flake outputs
nix flake show

# Check flake for errors
nix flake check

Basic Flake Template

{
  description = "NixOS configuration";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager = {
      url = "github:nix-community/home-manager";
      inputs.nixpkgs.follows = "nixpkgs";  # Avoid duplicate nixpkgs
    };
  };

  outputs = { self, nixpkgs, home-manager, ... }@inputs: {
    nixosConfigurations.hostname = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      specialArgs = { inherit inputs; };  # Pass inputs to modules
      modules = [
        ./configuration.nix
        home-manager.nixosModules.home-manager
        {
          home-manager.useGlobalPkgs = true;
          home-manager.useUserPackages = true;
          home-manager.users.username = import ./home.nix;
        }
      ];
    };
  };
}

Module Pattern with Options

# modules/home/git/default.nix
{ config, lib, pkgs, ... }:
let
  cfg = config.custom.git;
in {
  options.custom.git = {
    enable = lib.mkEnableOption "Git configuration";
    userName = lib.mkOption {
      type = lib.types.str;
      description = "Git user name";
    };
    userEmail = lib.mkOption {
      type = lib.types.str;
      description = "Git user email";
    };
  };

  config = lib.mkIf cfg.enable {
    programs.git = {
      enable = true;
      userName = cfg.userName;
      userEmail = cfg.userEmail;
      extraConfig = {
        init.defaultBranch = "main";
        pull.rebase = true;
      };
    };
  };
}

Secrets Management with sops-nix

# In flake.nix inputs
sops-nix.url = "github:Mic92/sops-nix";

# In configuration
sops = {
  defaultSopsFile = ./secrets/secrets.yaml;
  age.keyFile = "/var/lib/sops-nix/key.txt";
  secrets.my-secret = {};
};

Key Libraries

Library	Purpose
Snowfall Lib	Standardized config structure
sops-nix	Encrypted secrets in git
home-manager	User environment management
nix-darwin	macOS declarative config
flake-utils	Multi-system helpers
devenv	Simplified dev environments

When to Use What

• NixOS modules: System-wide packages, services, boot config
• home-manager: User dotfiles, user packages, per-user services
• nix-darwin: macOS system config (Homebrew, defaults, launchd)
• devShells: Project-specific development environments
• overlays: Package modifications, version pins, custom builds

Best Practices

1. Pin nixpkgs with flake.lock for reproducibility
2. Use follows to avoid duplicate nixpkgs in inputs
3. Prefer explicit package references over with pkgs
4. Keep secrets encrypted with sops-nix
5. Organize modules by feature, not by type
6. Use lib.mkIf for conditional configuration
7. Test configuration changes with nixos-rebuild build first
8. Regular garbage collection to save disk space
9. Use home-manager for user-specific configuration
10. Document your modules with descriptions