bun2nix

The Bun2Nix Catalog Template demonstrates how to use a Bun workspace project with the catalog: protocol to centralize dependency versions. This template is specifically designed to show how bun2nix handles both the default catalog and named catalogs (e.g., catalog:tooling).

Project Structure

• packages/app: A simple application that consumes the workspace library using the catalog: protocol.
• packages/lib: A library package that uses the default catalog to pin its npm dependencies.

The sample project demonstrates how bun2nix integrates with a standard Bun project. The following files are key to the integration:

• flake.nix: Provides the Nix Flake setup for the project.
• default.nix: Contains the specific Nix build instructions for the Bun package.
• bun.lock: The source of truth for Bun dependencies.
• bun.nix: The Nix expression generated by bun2nix from bun.lock.
• package.json: The standard JavaScript manifest, which includes a postinstall script that invokes bun2nix to ensure the Nix expressions are up to date.

The sample project demonstrates how bun2nix integrates with a standard Bun/Nix project through several key files:

• flake.nix: Defines the Nix Flake setup for the project.
• default.nix: Contains the specific build instructions for the Bun package.
• bun.lock: The source of truth for Bun dependencies.
• bun.nix: The output file generated by bun2nix from bun.lock.
• package.json: A standard JavaScript manifest that includes a postinstall script configured to trigger bun2nix.

The programs/bun2nix/templates/ directory contains rinja templates used internally by bun2nix to construct the output Nix files.

Note: This directory is for template definitions used by the tool itself. If you are looking for project templates to bootstrap your own Bun project with bun2nix integration, use the nix/templates/ folder instead.

The bun2nix tool is available in two flavors: WASM and Native. Choosing the right one depends on your environment and dependency types.

Use the WASM CLI if:

• You are working in environments where Nix is not installed (e.g., Windows users on a team).
• You are not using exotic dependency types like tarballs or git repositories.

Use the Native CLI if:

• Your team is already using Nix (this reduces overhead as it avoids running in a JavaScript runtime).
• You are using dependency types that require a prefetch, such as git or tarball dependencies.

When using bun2nix, your project will typically include the following key files:

• flake.nix: Contains the basic project setup for a Nix flake, enabling the use of bun2nix within the Nix ecosystem.
• default.nix: Contains the specific build instructions for the Bun package.
• bun.lock: The standard Bun lockfile used as the source of truth for dependencies.
• bun.nix: A file generated by bun2nix that contains the Nix expression derived from your bun.lock.
• package.json: A standard JavaScript package.json that includes a postinstall script configured to trigger bun2nix.

The authentication workflow follows these steps:

1. Generation Phase: When bun2nix generates the bun.nix file, it extracts the full tarball URLs from bun.lock for any packages hosted on non-default registries.
2. Evaluation Phase: When Nix evaluates fetchBunDeps, it parses the credentials from the files provided via bunfigPath or npmrcPath.
3. Request Phase: fetchBunDeps creates an authenticated fetchurl wrapper that automatically injects the appropriate Authorization headers for matching registry hosts.

Note: Packages from the default registry (registry.npmjs.org) do not require these credentials.

The bun2nix package exposes several specialized functions for building Bun-related packages. These functions are not top-level attributes of the Nixpkgs set but are available as attributes on the bun2nix package itself via its passthru attribute.

# Example pattern for accessing functions
let bun2nix = import <nixpkgs> { ... };
let bun2nixFunctions = bun2nix.passthru;
# Now you can use functions like bun2nixFunctions.mkDerivation

Projects using Bun's catalog: protocol are supported out of the box.

Because bun install re-resolves catalog: specifiers against the registry even with a populated cache, the hook runs bunResolveCatalogRefs immediately before bun install. This process:

1. Reads the exact pinned version for each package from bun.lock.
2. Rewrites every catalog: reference (in bun.lock's workspaces section and each workspace package.json) to that exact version, or to workspace:* for workspace packages.

This works for both the default catalog and named catalogs (e.g., catalog:<name>).