Nix-Direnv Setup

Overview

Standardized technique for setting up nix-direnv with automatic shell environment loading, proper git exclusions, and cross-project compatibility.

This skill blocks common rationalizations - follow exactly, especially under pressure.

When to Use

Use this skill when setting up direnv integration for Nix flake projects.

Perfect for:

• Creating .envrc files with use flake
• Automatic shell environment loading
• Team standardization of development environments

Not for:

• Git workflows (branches, worktrees, commits)
• General Nix package management
• Projects without flake.nix

Core Pattern

Before (Common mistakes):

# Trial and error approach
echo "use nix" > .envrc
direnv allow  # Fails - no shell.nix
echo "use flake" > .envrc
direnv allow  # Fails - no devShell
echo "use flake .#devShell" > .envrc
direnv allow  # Wrong syntax
# ...10+ minutes wasted

After (Standardized setup):

# One-time setup
echo "use flake" > .envrc
direnv allow

# Git exclusions handled automatically
# Project works immediately

Quick Reference

Implementation

Step 1: Create .envrc

# Create minimal .envrc
echo "use flake" > .envrc

# Test before allowing
direnv status

Commit .envrc to project - team-wide configuration

Step 2: Ensure devShell exists in flake.nix

# Reference: https://github.com/NixOS/templates
# Use templates as best practice guide

{
  outputs = { self, nixpkgs, ... }: {
    # Development shells for all platforms
    devShells = nixpkgs.lib.genAttrs [
      "aarch64-darwin" "x86_64-darwin"
      "x86_64-linux" "aarch64-linux"
    ] (system: let
      pkgs = nixpkgs.legacyPackages.${system};
    in {
      default = pkgs.mkShell {
        # Essential tools only
        packages = with pkgs; [ git jq nixfmt ];

        shellHook = ''
          echo "✨ Development environment ready"
        '';
      };
    });
  };
}

Step 3: Git Exclusions (Local Only)

# .git/info/exclude - NEVER commit this
# Personal developer files, not project-wide

# Build artifacts
result-*
.direnv/

# Local files
.env.local
.*.swp
*~

# Cache
.cache/
.nix-build/

# Test outputs
test-scenarios/
*.log

Use .git/info/exclude (local) vs .gitignore (shared)

Step 4: Enable and Test (NEVER SKIP)

# Enable direnv in this directory
direnv allow

# Test environment loading (MANDATORY verification)
direnv exec . bash -c "which git && echo '✅ Environment loaded'"

# Verify core functionality (REQUIRED)
direnv exec . nix flake show 2>/dev/null && echo "✅ Flake accessible" || echo "❌ Check flake.nix"
direnv exec . make --version >/dev/null 2>&1 && echo "✅ Build system accessible" || echo "❌ Check Makefile"

No exceptions: Verification is never optional. If tests fail, fix before proceeding.

Common Mistakes & Rationalization Blockers

Red Flags - STOP and Start Over

• "I'll skip this step"
• "This project is different"
• "I'll fix it after the demo"
• "The warnings don't matter"
• "Good enough for now"

All of these mean: You're about to create problems. Follow the skill exactly.

Cache Management

Normal behavior:

• .direnv/ appears (100-200MB) - this is expected
• Contains symlinked profile to Nix store
• Persists across sessions for speed

When to clean:

# If environment seems corrupted
rm -rf .direnv/
direnv allow  # Rebuild

Never commit .direnv/ - always exclude it.

Advanced Patterns

Multiple Development Shells

# .envrc (select specific shell)
use flake .#devShells.aarch64-darwin.backend

Development Variations

# With extra flags (rarely needed)
use flake --impure

# Non-flake projects
use nix

Reference NixOS templates for patterns:

• https://github.com/NixOS/templates/tree/main
• Study flake.nix in template projects
• Adapt patterns to your project structure

Real-World Impact

• Setup time: 10+ minutes → 2 minutes
• Team consistency: Everyone uses same approach
• Zero configuration drift: git-tracked .envrc
• Cross-project compatible: Works across all flake projects
• Cache efficiency: Proper management avoids unnecessary rebuilds