nix-ecosystem

name	Nix Ecosystem
description	This skill should be used when the user asks to "write nix", "nix expression", "flake.nix", "home-manager config", "programs.*", "services.*", or works with Nix language, flakes, or Home Manager. Provides comprehensive Nix ecosystem patterns and best practices.
version	0.1.0

Provide comprehensive patterns for Nix language, flakes, and Home Manager configuration.

<nix_language> Nix is lazily evaluated. Expressions are only computed when needed.

Only evaluates needed attributes

let expensive = builtins.trace "Computing expensive" (1 + 1); in { a = 1; b = expensive; }.a # Does not compute expensive

All Nix functions are pure. Same inputs always produce same outputs. Pure function - always returns same result for same input double = x: x * 2;

Avoid side effects; use derivations for build actions

buildResult = pkgs.stdenv.mkDerivation { ... };

Primary data structure in Nix Basic attribute set { attr1 = value1; attr2 = value2; }

Access patterns

set.attr set."attr-with-dashes"

Recursive attribute set

rec { a = 1; b = a + 1; }

Local bindings for complex expressions let helper = x: x + 1; value = helper 5; in value * 2 Bring attribute set into scope with pkgs; [ git vim tmux ] Avoid nested with; prefer explicit references for clarity Copy attributes from another set { inherit (pkgs) git vim; inherit name version; } Modify or extend nixpkgs final: prev: { myPackage = prev.myPackage.override { ... }; } Dependency injection pattern myPackage = pkgs.callPackage ./package.nix { }; Standard package builder pkgs.stdenv.mkDerivation { pname = "mypackage"; version = "1.0.0"; src = fetchFromGitHub { ... };

nativeBuildInputs = [ pkgs.cmake ]; buildInputs = [ pkgs.openssl ];

installPhase = '' mkdir -p $out/bin cp mypackage $out/bin/ ''; } Required attributes: pname, version, src Standard phases: unpackPhase, patchPhase, configurePhase, buildPhase, installPhase

Dependency specification in derivations { # Tools run at build time (compilers, build tools) nativeBuildInputs = [ cmake pkg-config ];

Libraries linked at runtime

buildInputs = [ openssl zlib ]; }

NixOS/Home Manager module structure { config, lib, pkgs, ... }: { options.myModule = { enable = lib.mkEnableOption "my module"; setting = lib.mkOption { type = lib.types.str; default = "value"; description = "A setting"; }; };

config = lib.mkIf config.myModule.enable { # configuration when enabled }; }

Define module options with types and defaults options.myOption = lib.mkOption { type = lib.types.bool; default = false; description = "Enable my feature"; example = true; }; Common types: lib.types.bool, lib.types.str, lib.types.listOf, lib.types.attrsOf Shorthand for boolean enable option enable = lib.mkEnableOption "my service";

<anti_patterns> Directly referencing absolute paths breaks reproducibility Use fetchurl, fetchFromGitHub, or relative paths within the repository

Multiple nested with statements reduce code clarity Prefer explicit attribute access (pkgs.git) for better readability Recursive attribute sets can be hard to understand and maintain Use let-in for complex recursive definitions Using string interpolation for path operations is error-prone Use lib functions for path manipulation (lib.concatStringsSep, builtins.path) Basic structure of a flake.nix file { description = "Project description";

inputs = { nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; };

outputs = { self, nixpkgs, ... }@inputs: { # output attributes }; }

Derivations for nix build packages.x86_64-linux.default = pkgs.hello; Development environments for nix develop devShells.x86_64-linux.default = pkgs.mkShell { packages = [ pkgs.nodejs ]; }; Runnable applications for nix run apps.x86_64-linux.default = { type = "app"; program = "${pkgs.hello}/bin/hello"; }; Nixpkgs overlays overlays.default = final: prev: { myPackage = prev.callPackage ./myPackage.nix { }; }; NixOS modules nixosModules.default = { config, lib, pkgs, ... }: { options.services.myService = { ... }; config = { ... }; }; Home Manager modules homeManagerModules.default = { config, lib, pkgs, ... }: { options.programs.myProgram = { ... }; config = { ... }; }; Full NixOS system configurations nixosConfigurations.hostname = nixpkgs.lib.nixosSystem { system = "x86_64-linux"; modules = [ ./configuration.nix ]; }; Home Manager configurations homeConfigurations."user@host" = home-manager.lib.homeManagerConfiguration { pkgs = nixpkgs.legacyPackages.x86_64-linux; modules = [ ./home.nix ]; }; Reference GitHub repositories as flake inputs inputs = { nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; # Specific branch stable.url = "github:NixOS/nixpkgs/nixos-24.11"; # Specific revision pinned.url = "github:owner/repo/abc123def"; }; Share input between flakes to avoid duplication home-manager = { url = "github:nix-community/home-manager"; inputs.nixpkgs.follows = "nixpkgs"; }; Non-flake inputs for legacy repositories my-source = { url = "github:owner/repo"; flake = false; }; Generate outputs for multiple systems outputs = { self, nixpkgs, ... }: let systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ]; forAllSystems = nixpkgs.lib.genAttrs systems; in { packages = forAllSystems (system: let pkgs = nixpkgs.legacyPackages.${system}; in { default = pkgs.hello; } ); }; Development environment with packages and hooks devShells.default = pkgs.mkShell { packages = with pkgs; [ nodejs yarn ]; shellHook = '' echo "Development environment ready" ''; }; Update all inputs to their latest versions Regular dependency updates Update a specific input Selective updates to test compatibility Display all flake outputs Exploring available packages and configurations Validate flake and run checks CI/CD validation, pre-commit checks

<home_manager> Standard Home Manager module structure { config, pkgs, lib, ... }: { options.custom.feature = { enable = lib.mkEnableOption "feature description"; };

config = lib.mkIf config.custom.feature.enable { # configuration when enabled }; }

Organize modules by program name home-manager/programs/git.nix home-manager/programs/neovim.nix home-manager/programs/tmux.nix Organize modules by category home-manager/development/default.nix home-manager/shell/default.nix home-manager/editors/default.nix Import multiple modules imports = [ ./programs/git.nix ./programs/neovim.nix ./shell/fish.nix ]; Enable a program with defaults programs.git.enable = true; Enable and configure a program programs.git = { enable = true; userName = "name"; userEmail = "email"; extraConfig = { core.editor = "nvim"; init.defaultBranch = "main"; }; }; Use alternative package version programs.git = { enable = true; package = pkgs.gitFull; }; Manage dotfiles directly home.file.".config/app/config" = { source = ./config; # or text = '' key = value ''; }; XDG config directory files xdg.configFile."app/config".source = ./config; Environment variables for login shells home.sessionVariables = { EDITOR = "nvim"; PAGER = "less"; }; Add directories to PATH home.sessionPath = [ "$HOME/.local/bin" ];

<common_modules> Git version control configuration programs.git = { enable = true; userName = "Your Name"; userEmail = "[e-mail]"; signing = { key = "KEY_ID"; signByDefault = true; }; aliases = { co = "checkout"; st = "status"; }; extraConfig = { core.editor = "nvim"; }; };

Neovim editor configuration programs.neovim = { enable = true; viAlias = true; vimAlias = true; plugins = with pkgs.vimPlugins; [ vim-commentary vim-surround ]; extraConfig = '' set number set relativenumber ''; extraLuaConfig = '' vim.opt.expandtab = true ''; }; Fish shell configuration programs.fish = { enable = true; shellInit = '' set -g fish_greeting ''; shellAliases = { ll = "ls -lah"; }; functions = { gitignore = "curl -sL https://www.gitignore.io/api/$argv"; }; plugins = [ { name = "z"; src = pkgs.fishPlugins.z.src; } ]; }; Terminal multiplexer configuration programs.tmux = { enable = true; terminal = "screen-256color"; keyMode = "vi"; plugins = with pkgs.tmuxPlugins; [ sensible yank ]; extraConfig = '' set -g mouse on ''; }; Directory-specific environment loader programs.direnv = { enable = true; nix-direnv.enable = true; enableBashIntegration = true; enableZshIntegration = true; };

<best_practices> Use programs.* when available instead of manual configuration

Set home.stateVersion to your initial HM version and do not change after initial setup unless migrating Group related configurations in separate modules for maintainability Use lib.mkIf for conditional configuration Prefer xdg.configFile over home.file for XDG-compliant apps Use home.packages for additional packages not configured via programs.* Track Home Manager state version for compatibility home.stateVersion = "24.11"; # Current stable. 25.05 (upcoming). Do not change after initial setup unless migrating HM 24.11+ (25.05 upcoming) supports minimal mode for faster evaluation imports = [ "${modulesPath}/programs/fzf.nix" ]; Advanced users optimizing evaluation time Basic NixOS configuration with Home Manager nixosConfigurations.hostname = nixpkgs.lib.nixosSystem { system = "x86_64-linux"; modules = [ ./configuration.nix home-manager.nixosModules.home-manager ]; specialArgs = { inherit inputs; }; }; Standalone Home Manager without NixOS homeConfigurations."user@host" = home-manager.lib.homeManagerConfiguration { pkgs = nixpkgs.legacyPackages.x86_64-linux; modules = [ ./home.nix ]; extraSpecialArgs = { inherit inputs; }; }; Home Manager as a NixOS module { imports = [ home-manager.nixosModules.home-manager ];

home-manager.useGlobalPkgs = true; home-manager.useUserPackages = true; home-manager.users.username = import ./home.nix; }