Bun

When Bun is the incumbent package manager, Nub installs against it and writes no lockfile of its own. The bun.lock text lockfile round-trips byte-for-byte; trustedDependencies, overrides / resolutions, patchedDependencies, and workspaces + catalogs all resolve the way Bun resolves them. Everything below is gated on Bun being the incumbent — a packageManager: "bun@…" field or an existing bun.lock.

Configuration

bun.lock

The text lockfile (Bun 1.2+ default) is read, written, and preserved as-is.

# captured: nub 0.0.44 — install in a bun.lock project, then diff the lockfile
$ nub install
dependencies:
+ is-odd@3.0.1

nub 0.0.44 · ✓ installed 2 packages in 38ms

$ diff bun.lock bun.lock.orig    # ✓ byte-identical (no output)
$ ls pnpm-lock.yaml              # ✓ no foreign lockfile written
ls: pnpm-lock.yaml: No such file or directory

bun.lockb

The legacy binary lockfile (pre-1.2) is not read. With only a bun.lockb and no text bun.lock, Nub refuses up front rather than guess or fall through to another format:

# captured: nub 0.0.44 — a project with only bun.lockb
$ nub install
ERR_NUB_LOCKFILE_PARSE          # ❌ binary format rejected

  × failed to parse lockfile
  ╰─▶ failed to parse lockfile /path/to/bun.lockb: bun.lockb
      (binary format) is not supported — run `bun install --save-text-
      lockfile` to generate a bun.lock text file first, or upgrade to bun 1.2+
      where text is the default

Run bun install --save-text-lockfile once to migrate, then Nub round-trips the resulting bun.lock.

trustedDependencies

Bun gates dependency build scripts behind a trustedDependencies allowlist in package.json. Nub mirrors it exactly when Bun is the incumbent: listed packages run their install/postinstall scripts, everything else is installed without building.

// package.json
{
  "dependencies": { "esbuild": "0.21.5" },
  "trustedDependencies": ["esbuild"]
}

# captured: nub 0.0.44 — esbuild NOT in trustedDependencies — build skipped
$ nub install
dependencies:
+ esbuild@0.21.5

nub 0.0.44 · ✓ installed 2 packages in 33ms
WARN ignored build scripts for 1 package(s): esbuild@0.21.5.
     Run `nub approve-builds` to review and enable them, or set
     `strictDepBuilds=true` to fail installs that have unreviewed builds.
     code=WARN_NUB_IGNORED_BUILD_SCRIPTS count=1 packages=["esbuild@0.21.5"]

# captured: nub 0.0.44 — esbuild IN trustedDependencies — build runs
$ nub install
dependencies:
+ esbuild@0.21.5

nub 0.0.44 · ✓ installed 2 packages in 35ms

Nub's curated default-trust floor is on, but inert over a bun.lock: its cooling-window gate needs per-package publish-time data, and bun.lock carries none, so it fails closed. Only trustedDependencies builds anything — exactly Bun's model.

bunfig.toml

Nub reads a small install-only subset of Bun config when Bun is the incumbent package manager: project bunfig.toml, plus global .bunfig.toml from XDG_CONFIG_HOME (or HOME when XDG_CONFIG_HOME is unset). Project config wins over global config.

Supported today:

• [install].registry as a string URL or { url, token, username, password } object. Auth-only objects without url apply to the default npm registry.
• [install.scopes] entries as string URLs or registry objects. Auth-only scoped objects inherit [install].registry, or the default npm registry when no default is configured, for registry routing.
• [install].cafile (a path to a PEM file) and [install].ca (inline PEM, single string or array), mapped onto the same TLS trust the .npmrc cafile / ca keys feed.
• [install].minimumReleaseAge and [install].minimumReleaseAgeExcludes, converted from bunfig's seconds to Nub's minutes.

Plus BUN_CONFIG_REGISTRY and BUN_CONFIG_TOKEN from the environment, which set the default registry and its auth token and outrank the file config.

Not read: [install].linker. A Bun-owned project selects the layout through the neutral .npmrc key or the CLI flag. See resolution versus layout.

Nub identity, npm, pnpm, yarn, and fresh projects do not read bunfig.toml; the file is Bun-owned config and stays inert unless Bun is the incumbent. This launch subset is best-effort: unreadable or invalid TOML is ignored instead of failing the install.

Gaps

• Install-only bunfig.toml. The [install] keys (registry, scopes, TLS, release-age gate) are read; linker, runtime/test/serve fields, the security scanner, cache and global-dir behavior, and the wider BUN_CONFIG_* install-behavior family (retry, lockfile, and skip toggles) have no effect. Custom CAs work through bunfig's own [install] cafile and ca keys as well as .npmrc — the .npmrc cafile / ca keys (top-level and per-registry) work under every incumbent, see Custom CAs. For registry, auth, or TLS that must be shared across tools, .npmrc is the most portable home:

  # .npmrc — honored by both nub and bun
  //registry.example.com/:_authToken=${NPM_TOKEN}
  @myscope:registry=https://registry.example.com/
  cafile=./corp-ca.pem

  Scope-local credentials that use the same registry URL as the default registry are also not faithfully representable in Nub's current registry model. Nub keeps the scoped registry route, but does not widen those credentials into registry-wide auth.

• No bun.lockb. The binary lockfile is rejected, not migrated — run bun install --save-text-lockfile to produce a bun.lock first.

• Default-trust floor inert over bun.lock. No publish-time data means curated packages aren't auto-trusted; only trustedDependencies builds.