Bun Workspaces

Bun Workspaces

Use one root workspace and lockfile, resolve internal packages through workspace:* links and package exports, and choose script scheduling from dependency order and task lifetime. Do not hide packaging errors with TypeScript source aliases.

Current baseline

Verified against Bun 1.3.14 on 2026-08-03:

bun --version

New workspace projects with lockfile configVersion = 1 default to the isolated linker. Existing and migrated projects preserve historical linker choices. Bun 1.3.14 adds an experimental isolated-linker global virtual store that is off by default.

Read references/releases.md for the 49-page research ledger. Read references/linkers-dependencies-and-lockfiles.md for linker, store, catalogs, dependency classes, lifecycle trust, and migration. Read references/scripts-builds-and-publishing.md for filters, scheduling, package exports, TypeScript, CI, containers, audit, pack, and publish.

Workspace declaration

The root owns the workspace patterns and shared lockfile:

{
  "private": true,
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "typescript": "^7.0.0"
    },
    "catalogs": {
      "testing": {
        "@types/bun": "latest"
      }
    }
  }
}

catalog: resolves the singular default catalog. A named catalog entry uses catalog:name. Do not put a named default group under catalogs and reference it as bare catalog:.

Internal package dependency:

{
  "dependencies": {
    "@example/shared": "workspace:*"
  }
}

Bun rewrites workspace and catalog protocols appropriately during publication.

Linker selection

Set the linker explicitly when deterministic strictness is required:

[install]
linker = "isolated"

Isolated installs prevent phantom dependencies and create peer-set-specific package identities. Test tools and bundlers against the real layout; do not depend on accidental hoisting.

Cache versus global store

The global cache at ~/.bun/install/cache stores fetched package content and metadata. The experimental global virtual store is different: it is isolated-linker-only, disabled by default, and symlinks projects through the cache's links area.

[install]
globalStore = true

Keep this setting machine-local unless the repository has revalidated parallel CI behavior. General upstream race-safety claims do not supersede the repository's known shared-store CI constraint.

Dependencies

Bun installs peer and optional dependencies by default. peerDependenciesMeta.optional means a peer may be absent; it does not force installation.

bun add --cwd packages/shared lodash
bun add --cwd packages/plugin --peer react
bun add --cwd packages/tool --optional native-addon

bun add does not have --filter; use --cwd or run from the package directory. Use omit flags only when the install contract intentionally excludes peer/optional packages.

Lockfile and CI

bun.lock is the authoritative text lockfile. Use:

bun ci

bun ci is the concise frozen install. bun install --lockfile-only skips node_modules installation but writes the lockfile and can populate global cache metadata or Git/tarball dependencies.

Yarn v1 lockfile printing creates an interoperability artifact on every install; do not make it a generic default.

For bun.lockb migration, generate and inspect bun.lock, run a clean frozen install and focused verification, then remove the preserved binary source lockfile. Automatic migration occurs only when bun.lock is absent.

Lifecycle trust

Dependency lifecycle scripts are allow-listed. trustedDependencies replaces Bun's built-in trusted list rather than extending it; an empty list trusts none. Non-registry sources require explicit trust.

--ignore-scripts disables project and trusted dependency lifecycle scripts. In bunfig, use ignoreScripts; there is no documented lifecycle = ["postinstall"] policy setting.

Review untrusted scripts before enabling them:

bun pm untrusted
bun pm trust <package>

Script scheduling

Filtered finite scripts honor workspace dependency order; independent packages can overlap. Keep local builds focused:

bunx turbo run build --filter=<workspace>

At this monorepo's root, use bunx turbo run build for repo-wide and focused builds so dependencies run in task-graph order. Never use bun run --filter '*' build here: bypassing the bounded Turbo task graph can launch thousands of processes and exhaust the machine.

Long-running dev servers block dependents under dependency ordering. Start only the intended independent servers. Run each selected workspace in its own terminal, or use the repository's bounded dev orchestrator:

# terminal 1
bun run --filter '<workspace-a>' dev

# terminal 2
bun run --filter '<workspace-b>' dev

Focused execution remains the default during development. Do not apply blanket parallelism to builds whose order matters.