Nix Helper

Provide guidance for managing Nix configurations in this dotfiles repository.

Configuration Overview

This dotfiles repository uses:

•Nix Flakes as the primary configuration entry point
•nix-darwin for macOS system-level configuration
•Home Manager for user-level configuration
•SOPS for secrets management
•nvfetcher for external packages not in nixpkgs
•edgepkgs overlay for bleeding-edge packages

Directory Structure

code

.
├── flake.nix              # Entry point (inputs, outputs, host configurations)
├── hosts/                 # Machine-specific configurations
│   ├── kohei-m4-mac-mini/ # Personal machine config
│   └── SC-N-843/          # Work machine config
├── nix-darwin/            # System-level macOS configurations
│   ├── default.nix        # Full configuration (personal machines)
│   └── minimum-for-work.nix # Minimal configuration (work machines)
├── home-manager/          # User-level configurations
│   ├── programs/          # Individual program configurations
│   ├── pkgs/              # Package list (default.nix)
│   ├── services/          # User-level services
│   └── files.nix          # Out-of-store symlink configuration
├── configs/               # Raw configuration files (Neovim, WezTerm, etc.)
├── secrets/               # SOPS-encrypted secrets
└── _sources/              # Auto-generated by nvfetcher

Common Tasks

Adding a New Package

Edit home-manager/pkgs/default.nix:

nix

home.packages = with pkgs; [
  # ... existing packages
  new-package-name
];

For bleeding-edge packages, use the edgepkgs overlay:

nix

home.packages = [
  pkgs.edge.package-name  # From nixpkgs HEAD
];

See references/package-management.md for nvfetcher and external package patterns.

Adding a New Program Configuration

•Create directory: home-manager/programs/<program-name>/
•Create default.nix:

nix

{ pkgs, ... }:
{
  programs.<program-name> = {
    enable = true;
    # Configuration options
  };
}

•Import in home-manager/programs/default.nix:

nix

let
  new-program = import ./new-program { inherit pkgs; };
in
[
  # ... existing programs
  new-program
]

See examples/new-program.nix.example for complete examples.

Adding Config Files with Out-of-Store Symlinks

Use out-of-store symlinks for configs that need editing without Nix rebuild.

•Place files in configs/.config/<app-name>/
•Edit home-manager/files.nix:

nix

xdg.configFile."app-name" = {
  source = symlink /${rootDir}/.config/app-name;
  recursive = true;
};

See examples/out-of-store-symlink.nix.example for patterns.

Working with Secrets

Edit encrypted secrets:

bash

sops secrets/default.yaml

Define in module:

nix

sops.secrets.my-secret = { };

Use the secret path:

nix

config.sops.secrets.my-secret.path

See references/secrets-management.md for detailed SOPS workflow.

Building and Applying Changes

bash

# Apply configuration for specific host
sudo darwin-rebuild switch --flake .#kohei-m4-mac-mini
sudo darwin-rebuild switch --flake .#SC-N-843

# Format all Nix and Lua files
nix fmt

# Update all flake inputs
nix run .#update

# Run pre-commit hooks
nix develop -c pre-commit run --all-files

Key Patterns

userConfig Pattern

Each host defines a userConfig object passed to all modules:

nix

userConfig = {
  username = "thinceller";
  homeDir = "/Users/${username}";
  hostname = "kohei-m4-mac-mini";
  dotfilesDir = homeDir + "/.dotfiles";
};

Access in modules via specialArgs:

nix

{ userConfig, ... }:
{
  home.username = userConfig.username;
}

Module Import Pattern

Programs return lists for flexible composition:

nix

# home-manager/default.nix
imports = programs ++ files ++ packages ++ services;

External Package Pattern (nvfetcher)

•Define in nvfetcher.toml
•Run nvfetcher to generate _sources/generated.nix
•Import and use:

nix

sources = pkgs.callPackage ../_sources/generated.nix { };
package = sources.package-name;

See references/package-management.md for detailed examples.

Troubleshooting

Build Errors

bash

# Validate flake
nix flake check

# Show detailed error
nix build --show-trace

# Test configuration without applying
darwin-rebuild build --flake .#<hostname>

Common Issues

Issue	Solution
Package not found	Verify name in nixpkgs or use nvfetcher
Import errors	Check module path and return type (list vs attrset)
Symlink conflicts	Remove existing files before rebuild
SOPS decryption fails	Verify age key at `~/.config/sops/age/keys.txt`

Flake Lock Updates

bash

# Update specific input
nix flake lock --update-input <input-name>

# Update all inputs
nix run .#update

Adding a New Host

•Create hosts/<hostname>/default.nix
•Define userConfig:

nix

userConfig = {
  username = "username";
  homeDir = "/Users/${username}";
  hostname = "<hostname>";
  dotfilesDir = homeDir + "/.dotfiles";
};

•Choose nix-darwin module (full or minimum-for-work)
•Add to flake.nix darwinConfigurations

See examples/new-host.nix.example for complete template.

Additional Resources

•references/package-management.md - nvfetcher, edgepkgs, external packages
•references/secrets-management.md - SOPS workflow and best practices
•references/home-manager-patterns.md - Program configuration patterns
•examples/new-program.nix.example - Program configuration template
•examples/new-host.nix.example - Host configuration template
•examples/out-of-store-symlink.nix.example - Symlink configuration patterns