Nix Best Practices

alleneubank/claude-code/.claude/skills/nix-best-practices

作者 alleneubank2921eb8a685a无许可证52 个星标收录于 2026年10月8日更新于 2026年10月8日仓库3个月前更新

Use when working with Nix flakes, overlays, shell.nix, or flake.nix files.

已归档仅含说明Software DevelopmentDevOps & Cloud
AI 生成的概览

编写 Nix flake、overlay、开发环境以及处理非自由软件包的参考指南。

功能
提供 Nix flake 结构、输入 follows 链式引用、应用 overlay、处理非自由软件包、构建二进制 overlay 仓库、开发环境、direnv 集成以及常用命令的约定与代码模式。还列出常见 flake 错误的排查步骤，例如缺少输入、非自由软件包失败、重复下载 nixpkgs 和哈希不匹配。它只是纯说明性参考，不生成文件或脚本。
适用场景
在编写或审查 flake.nix、shell.nix 或 overlay 定义时使用，也适合排查 Nix flake 报错。适合需要开发环境、overlay 和非自由软件包配置成熟模式的开发者。
运行要求
不附带脚本或工具，仅为说明性内容。按指南操作需要已启用 flakes 的 Nix 环境，并需要网络访问以获取 flake 输入和二进制文件。

Nix Best Practices

Flake Structure

Standard flake.nix structure:

nix
{  description = "Project description";
  inputs = {    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";    flake-utils.url = "github:numtide/flake-utils";  };
  outputs = { self, nixpkgs, flake-utils }:    flake-utils.lib.eachDefaultSystem (system:      let        pkgs = import nixpkgs {          inherit system;        };      in {        devShells.default = pkgs.mkShell {          buildInputs = with pkgs; [            # packages here          ];        };      });}

Follows Pattern (Avoid Duplicate Nixpkgs)

When adding overlay inputs, use follows to share the parent nixpkgs and avoid downloading multiple versions:

nix
inputs = {  nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  # Overlay follows parent nixpkgs  some-overlay.url = "github:owner/some-overlay";  some-overlay.inputs.nixpkgs.follows = "nixpkgs";
  # Chain follows through intermediate inputs  another-overlay.url = "github:owner/another-overlay";  another-overlay.inputs.nixpkgs.follows = "some-overlay";};

All inputs must be listed in outputs function even if not directly used:

nix
outputs = { self, nixpkgs, some-overlay, another-overlay, ... }:

Applying Overlays

Overlays modify or add packages to nixpkgs:

nix
let  pkgs = import nixpkgs {    inherit system;    overlays = [      overlay1.overlays.default      overlay2.overlays.default      # Inline overlay      (final: prev: {        myPackage = prev.myPackage.override { ... };      })    ];  };in

Handling Unfree Packages

Option 1: nixpkgs-unfree (Recommended for Teams)

Use numtide/nixpkgs-unfree for EULA-licensed packages without requiring user config:

nix
inputs = {  nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";  nixpkgs-unfree.url = "github:numtide/nixpkgs-unfree/nixos-unstable";  nixpkgs-unfree.inputs.nixpkgs.follows = "nixpkgs";
  # Unfree overlay follows nixpkgs-unfree  proprietary-tool.url = "github:owner/proprietary-tool-overlay";  proprietary-tool.inputs.nixpkgs.follows = "nixpkgs-unfree";};

This chains: proprietary-tool → nixpkgs-unfree → nixpkgs

Option 2: User Config

Users add to ~/.config/nixpkgs/config.nix:

nix
{ allowUnfree = true; }

Option 3: Specific Packages (Flake)

nix
let  pkgs = import nixpkgs {    inherit system;    config.allowUnfreePredicate = pkg: builtins.elem (lib.getName pkg) [      "specific-package"    ];  };in

Note: config.allowUnfree in flake.nix doesn't work with nix develop - use nixpkgs-unfree or user config.

Creating Binary Overlay Repos

When nixpkgs builds a community version lacking features (common with open-core tools), create an overlay that fetches official binaries.

Pattern (see 0xBigBoss/atlas-overlay, 0xBigBoss/bun-overlay)

nix
{  inputs = {    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";    flake-utils.url = "github:numtide/flake-utils";  };
  outputs = { self, nixpkgs, flake-utils }:    flake-utils.lib.eachDefaultSystem (system:      let        pkgs = nixpkgs.legacyPackages.${system};
        version = "1.0.0";
        # Platform-specific binaries        sources = {          "x86_64-linux" = {            url = "https://example.com/tool-linux-amd64-v${version}";            sha256 = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";          };          "aarch64-linux" = {            url = "https://example.com/tool-linux-arm64-v${version}";            sha256 = "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=";          };          "x86_64-darwin" = {            url = "https://example.com/tool-darwin-amd64-v${version}";            sha256 = "sha256-CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=";          };          "aarch64-darwin" = {            url = "https://example.com/tool-darwin-arm64-v${version}";            sha256 = "sha256-DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD=";          };        };
        source = sources.${system} or (throw "Unsupported system: ${system}");
        toolPackage = pkgs.stdenv.mkDerivation {          pname = "tool";          inherit version;
          src = pkgs.fetchurl {            inherit (source) url sha256;          };
          sourceRoot = ".";          dontUnpack = true;
          installPhase = ''            mkdir -p $out/bin            cp $src $out/bin/tool            chmod +x $out/bin/tool          '';
          meta = with pkgs.lib; {            description = "Tool description";            homepage = "https://example.com";            license = licenses.unfree;  # or appropriate license            platforms = builtins.attrNames sources;          };        };      in {        packages.default = toolPackage;        packages.tool = toolPackage;
        overlays.default = final: prev: {          tool = toolPackage;        };      })    // {      overlays.default = final: prev: {        tool = self.packages.${prev.system}.tool;      };    };}

Getting SHA256 Hashes

bash
nix-prefetch-url https://example.com/tool-linux-amd64-v1.0.0# Returns hash in base32, convert to SRI format:nix hash to-sri --type sha256 <base32-hash>

Or use SRI directly:

bash
nix-prefetch-url --type sha256 https://example.com/tool-linux-amd64-v1.0.0

Dev Shell Patterns

Basic Shell

nix
devShells.default = pkgs.mkShell {  buildInputs = with pkgs; [    nodejs    python3  ];
  shellHook = ''    echo "Dev environment ready"  '';};

With Environment Variables

nix
devShells.default = pkgs.mkShell {  buildInputs = with pkgs; [ postgresql ];
  # Set at shell entry  DATABASE_URL = "postgres://localhost/dev";
  # Or in shellHook for dynamic values  shellHook = ''    export PROJECT_ROOT="$(pwd)"  '';};

Native Dependencies (C Libraries)

nix
devShells.default = pkgs.mkShell {  buildInputs = with pkgs; [    openssl    postgresql  ];
  # Expose headers and libraries  shellHook = ''    export C_INCLUDE_PATH="${pkgs.openssl.dev}/include:$C_INCLUDE_PATH"    export LIBRARY_PATH="${pkgs.openssl.out}/lib:$LIBRARY_PATH"    export PKG_CONFIG_PATH="${pkgs.openssl.dev}/lib/pkgconfig:$PKG_CONFIG_PATH"  '';};

Direnv Integration

.envrc for flake projects:

bash
use flake

For unfree packages without nixpkgs-unfree:

bash
export NIXPKGS_ALLOW_UNFREE=1use flake --impure

Common Commands

bash
# Update all inputsnix flake update
# Update specific inputnix flake update some-input
# Check flake validitynix flake check
# Show flake metadatanix flake metadata
# Enter dev shellnix develop
# Run command in dev shellnix develop -c <command>
# Build packagenix build .#packageName
# Run packagenix run .#packageName

Troubleshooting

"unexpected argument" Error

All inputs must be listed in outputs function:

nix
# Wrongoutputs = { self, nixpkgs }: ...
# Right (if you have more inputs)outputs = { self, nixpkgs, other-input, ... }: ...

Unfree Package Errors with nix develop

config.allowUnfree in flake.nix doesn't propagate to nix develop. Use:

  1. nixpkgs-unfree input (recommended)
  2. User's ~/.config/nixpkgs/config.nix
  3. NIXPKGS_ALLOW_UNFREE=1 nix develop --impure

Duplicate Nixpkgs Downloads

Use follows to chain inputs to a single nixpkgs source.

Overlay Not Applied

Ensure overlay is in the overlays list when importing nixpkgs:

nix
pkgs = import nixpkgs {  inherit system;  overlays = [ my-overlay.overlays.default ];};

Hash Mismatch

Re-fetch with nix-prefetch-url and update the hash. Hashes change when upstream updates binaries at the same URL.

来源与署名

来源：alleneubank/claude-code位于.claude/skills/nix-best-practices提交2921eb8

许可证： 无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 alleneubank/claude-code 的技能

React Best Practices

alleneubank

为 React 组件编写提供规范，涵盖 Effect、ref、自定义 Hook 与组件组合。

已归档
Software Development523个月前更新

Web Fetch

alleneubank

抓取网页并转换为干净的 Markdown，优先使用原生 Markdown 响应，其次用 CSS 选择器或内置 Bun 脚本。

包含脚本已归档
Research & Analysis523个月前更新

Typescript Best Practices

alleneubank

以类型优先、函数式和错误处理模式指导 TypeScript 与 JavaScript 编码。

已归档
Software Development523个月前更新

Zig Best Practices

alleneubank

提供 Zig 编码惯例指导：类型系统模式、内存管理、约定、工具与进阶主题。

已归档
Software Development523个月前更新

Python Best Practices

alleneubank

以类型优先、函数式和错误处理模式指导 Python 编码风格。

已归档
Software Development523个月前更新

更多Software Development技能

Playground

anthropics

精选

构建自包含的交互式 HTML 演练场，包含控件、实时预览和可复制的提示词输出。

Software Development37K今天更新

M5 Onboard

anthropics

精选

通过 USB 检测 M5Stack ESP32 开发板，刷写 UIFlow 2.0 固件并安装 MicroPython 应用包。

Software Development37K今天更新

Cardputer Buddy

anthropics

精选

指导迭代 Cardputer-Adv 的 MicroPython 应用包：添加应用、通过 USB 串口推送文件、查看日志并运行 REPL 命令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精选

依据从远程来源获取的 Web Interface Guidelines 审查 UI 代码，并以 file:line 形式报告问题。

Software Development32K5周前更新

Vercel React Native Skills

vercel-labs

精选

React Native 与 Expo 最佳实践规则，涵盖列表性能、动画、导航、UI 模式、状态与 monorepo 配置。

Software Development32K5周前更新

Vercel React Best Practices

vercel-labs

精选

Vercel 的 React 与 Next.js 性能指南，以 70 条规则的形式用于编写、审查和重构代码。

Software Development32K5周前更新