Bun Workspaces: Monorepo Dependency Management
Bun workspaces install and link many packages in a monorepo from a single bun install, declared by the workspaces field in the root package.json.
Workspaces are how Bun does monorepos. One install resolves every package, hoists shared dependencies, and symlinks internal packages so they import each other without publishing.
What it does
The workspaces array in the root package.json lists package globs (for example packages/*). bun install then resolves all of them together, installs dependencies once with hoisting, and symlinks internal packages into each other's node_modules. bun run and bun test accept --filter to target specific workspaces.
Common usage
// root package.json
{ "workspaces": ["packages/*", "apps/*"] }
bun install # installs all workspaces
bun run --filter './packages/*' build
bun test --filter @myorg/coreOptions
| Item | What it does |
|---|---|
| "workspaces": [...] | Root package.json globs naming the packages |
| --filter <pattern> | Run a script/test in matching workspaces |
| workspace:* (dependency) | Reference a sibling package by workspace protocol |
| bun install | One install resolves and links every workspace |
In CI
Run a single bun install --frozen-lockfile at the repo root; there is one bun.lock for the whole workspace. Cache ~/.bun/install/cache once for all packages. Use bun run --filter to build only affected workspaces, and prefer the workspace:* protocol over bun link for internal dependencies so CI resolves them deterministically.
Common errors in CI
"workspace dependency <pkg> not found" means an internal package name in a workspace:* dependency does not match a package.json name in the workspace globs. "error: Workspace not found" from --filter means the pattern matches nothing; check the path and package name. A package missing from the install usually fell outside the workspaces globs.