Package manager

Common commands

bun install
bun add zod
bun add -d typescript
bun remove zod
bun update
bun outdated
bun audit
bunx <package>
bun pm untrusted

Lockfile

bun install creates the text-based bun.lock. Commit it, and use the explicit CI command:

bun ci

bun ci is equivalent to bun install --frozen-lockfile and fails when the manifest and lockfile disagree.

When bun.lock is absent, Bun can migrate package-lock.json, yarn.lock, or pnpm-lock.yaml while preserving the original. Use this workflow:

1. Run bun install on a separate branch.
2. Review bun.lock and package.json changes.
3. Run the entire test and build pipeline.
4. Remove the old lockfile only after the team approves the switch, leaving one source of truth.

Workspaces

{
  "name": "acme-workspace",
  "private": true,
  "workspaces": ["apps/*", "packages/*"]
}

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

bun install --filter './apps/web'
bun run --filter '*' test

Continue with Monorepos and workspaces for Catalogs, dependency isolation, and task orchestration.

bunfig.toml

Create it only for Bun-specific behavior:

[install]
exact = true

[install.lockfile]
save = true

Prefer ecosystem-standard files such as package.json and tsconfig.json for settings they already own.

CI baseline

- uses: oven-sh/setup-bun@v2
- run: bun ci
- run: bun run typecheck
- run: bun test
- run: bun run build

Lifecycle scripts and supply-chain controls

Bun does not run arbitrary dependency lifecycle scripts by default, but it has a built-in default trust list and lets the project opt packages in through trustedDependencies. Installation can therefore still execute code:

bun pm untrusted
bun pm trust <package>         # only after reviewing it
bun install --ignore-scripts  # stricter CI mode; verify compatibility first
bun audit --prod               # production deps only; has filtering gaps at workspace roots

You can also delay newly published versions from entering an install:

[install]
minimumReleaseAge = 259200 # 3 days, in seconds

The age gate affects newly resolved versions, not packages already present in bun.lock. bun add -E <package> pins a direct dependency version, while the lockfile remains responsible for the complete graph.

Official references: Package manager, Lockfile, Lifecycle scripts, and Audit.