nix-developer

name	nix-developer
description	Develop declarative Nix and NixOS configurations. Use when the user asks to create, update, or debug Nix code, Nix development shells, Home Manager setups, NixOS hosts, or reproducible environments, or you need to develop Nix code.
license	MIT

Nix Developer

This skill provides expertise in developing modern, reproducible Nix and NixOS configurations.

Core Principles

• Prefer Flakes: Always default to using Nix Flakes (flake.nix) for new configurations and shells, as they are the modern standard for reproducibility.
• Declarative Over Imperative: Avoid nix-env or imperative state manipulation. Everything should be declared in code.
• Formatting and linting: Configure treefmt to run nixfmt, deadnix, and statix. Run formatting with nix fmt. For more information, see references/nix-treefmt.md.

Workflows

1. Set up a project environment

When tasked with setting up a project environment:

• Create a flake.nix with an outputs function providing a devShells.<system>.default.
• Use mkShell from nixpkgs to define buildInputs (runtime dependencies) and nativeBuildInputs (build tools).
• Include standard development tools (e.g., linters, LSPs) relevant to the project's primary languages.
• Recommend setting up direnv with use flake in .envrc for automatic shell loading.

2. NixOS Host Configuration

When configuring a NixOS machine, prioritize testability and separation of concerns by splitting configuration layers:

• Logical Configuration (configuration.nix): Declare all logical features—roles, logical packages, system services (e.g. SSH), local users, state version, and network parameters. This file should remain agnostic of physical hardware.
• Physical Entrypoint (default.nix): A thin entrypoint module that only imports the logical configuration (configuration.nix), physical hardware profile (hardware.nix), and disk partition definitions (disko.nix).
• Submodule Encapsulation: Keep the high-level entrypoint clean by importing hardware/filesystem modules (e.g., inputs.disko.nixosModules.disko) directly inside the configuration submodules that require them (e.g., disko.nix), rather than at the top level.
• Expose via Flakes: Expose the complete target system under nixosConfigurations in flake.nix importing the physical default.nix entrypoint.

3. Home Manager (User Environment)

When configuring user-specific dotfiles or packages:

• Utilize home-manager as a NixOS module or as a standalone flake output.
• Structure configurations by grouping related programs (e.g., git, shell, editor).

4. Integration Testing & Verification

To verify NixOS host configurations in a robust, reproducible way, implement sandboxed VM integration tests:

• Service-Aware VM Testing: Use the NixOS test framework (nixosTest / pkgs.testers.nixosTest) to run VMs in QEMU. Prioritize declarative, auto-deriving test generators (make-test.nix) that analyze the host's evaluated system configuration to dynamically provision QEMU serial devices and dynamically concatenate Python test assertions.
• Zero-Maintenance Flake Discovery: Avoid manual check declarations. Configure flake.nix checks to auto-scan the hosts/ directory and automatically register any host that has a test.nix file, ensuring CI instantly tests any new host configuration.
• Pure-Evaluation Mocking: Utilize conditional paths (builtins.pathExists) and VM-overrides (lib.mkVMOverride) in the test suite to dynamically mock out private/non-tracked keys and configuration files, ensuring isolated tests evaluate successfully.
• Read the Reference Guide: For a complete walkthrough, implementation example, and advanced debugging/mocking tips, see references/nix-testing.md.

Best Practices

• Pinning: Keep inputs pinned and explicitly manage flake.lock.
• Modularity: Split large configurations into separate modules using the imports = [ ... ]; pattern.
• Reviewing Changes: When modifying configurations, review the resulting diffs and use nix flake check or nix build to validate syntax and evaluation before applying.
• Developer Workflow & Debugging:
  • Use nix eval --raw .#checks.<system>.<test-name>.testScript to dry-run evaluate and inspect compiled Python test scripts without booting a VM.
  • When writing VM test assertions for asynchronous services (like QEMU guest agent), use machine.wait_for_file to block until udev creates the device node before asserting on the service unit.
  • See references/nix-testing.md for advanced testing best practices.

Flake development

• Explicitly pin the flake to a release branch (e.g., url = "github:NixOS/nixpkgs/nixos-25.11").
• Use inputs.nixpkgs.follows to unify nixpkgs across all inputs.
• Pass inputs to modules using specialArgs = { inherit inputs; }.

References

• Nix command reference
• treefmt example
• NixOS Integration Testing Reference Guide