Workspaces - Bun

Workspaces - BunDocumentation Index

Fetch the complete documentation index at: /docs/llms.txt

Use this file to discover all available pages before exploring further.

Skip to main contentBun home pageSearch...⌘KInstall BunSearch...NavigationWorkspace ManagementWorkspacesRuntimePackage ManagerBundlerTest RunnerGuidesReferenceBlogFeedback:first-child]:!hidden peer-[.is-custom]:[&>:first-child]:sm:!hidden peer-[.is-custom]:[&>:first-child]:md:!hidden peer-[.is-custom]:[&>:first-child]:lg:!hidden peer-[.is-custom]:[&>:first-child]:xl:!hidden">Core Commandsbun installbun addbun removebun updatebunxPublishing & Analysisbun publishbun outdatedbun whybun auditbun infoWorkspace ManagementWorkspacesCatalogsbun linkbun pmAdvanced Configurationbun patchbun --filterGlobal cacheGlobal virtual storeIsolated installsLockfileLifecycle scriptsScopes and registriesOverrides and resolutionsSecurity Scanner API.npmrc supportOn this pageShare versions with CatalogsWorkspace ManagementWorkspacesCopy pagespan]:line-clamp-1 overflow-hidden group flex items-center py-0.5 gap-1 text-sm text-gray-950/50 dark:text-white/50 group-hover:text-gray-950/70 dark:group-hover:text-white/70 rounded-none rounded-r-xl border px-3 border-gray-200 aspect-square dark:border-white/[0.07] bg-background-light dark:bg-background-dark hover:bg-gray-600/5 dark:hover:bg-gray-200/5" aria-label="More actions" type="button" id="radix-_R_n4ctdbsnlht5lebsnpfdb_" aria-haspopup="menu" aria-expanded="false" data-state="closed">*]:[overflow-wrap:anywhere]">

Develop complex monorepos with multiple independent packages

Copy pagespan]:line-clamp-1 overflow-hidden group flex items-center py-0.5 gap-1 text-sm text-gray-950/50 dark:text-white/50 group-hover:text-gray-950/70 dark:group-hover:text-white/70 rounded-none rounded-r-xl border px-3 border-gray-200 aspect-square dark:border-white/[0.07] bg-background-light dark:bg-background-dark hover:bg-gray-600/5 dark:hover:bg-gray-200/5" aria-label="More actions" type="button" id="radix-_R_1cctdbsnlht5lebsnpfdb_" aria-haspopup="menu" aria-expanded="false" data-state="closed">Bun supports workspaces in package.json. Workspaces let you develop complex software as a monorepo consisting of several independent packages. It’s common for a monorepo to have the following structure: File Tree

├── README.md
├── bun.lock
├── package.json
├── tsconfig.json
└── packages
   ├── pkg-a
   │   ├── index.ts
   │   ├── package.json
   │   └── tsconfig.json
   ├── pkg-b
   │   ├── index.ts
   │   ├── package.json
   │   └── tsconfig.json
   └── pkg-c
   ├── index.ts
   ├── package.json
   └── tsconfig.json

In the root package.json, the "workspaces" key is used to indicate which subdirectories should be considered packages/workspaces within the monorepo. It’s conventional to place all the workspace in a directory called packages. package.json

{
"name": "my-project",
"version": "1.0.0",
"workspaces": ["packages/*"],
"devDependencies": {
"example-package-in-monorepo": "workspace:*"
}
}

Glob support — Bun supports full glob syntax in "workspaces", including negative patterns (e.g. !**/excluded/**). See here for a comprehensive list of supported syntax. package.json

{
"name": "my-project",
"version": "1.0.0",
"workspaces": ["packages/**", "!packages/**/test/**", "!packages/**/template/**"]
}

Each workspace has it’s own package.json. When referencing other packages in the monorepo, semver or workspace protocols (e.g. workspace:*) can be used as the version field in your package.json. packages/pkg-a/package.json

{
"name": "pkg-a",
"version": "1.0.0",
"dependencies": {
"pkg-b": "workspace:*"
}
}

bun install will install dependencies for all workspaces in the monorepo, de-duplicating packages if possible. If you only want to install dependencies for specific workspaces, you can use the --filter flag.

# Install dependencies for all workspaces starting with `pkg-` except for `pkg-c`
bun install --filter "pkg-*" --filter "!pkg-c"

# Paths can also be used. This is equivalent to the command above.
bun install --filter "./packages/pkg-*" --filter "!pkg-c" # or --filter "!./packages/pkg-c"

When publishing, workspace: versions are replaced by the package’s package.json version,

"workspace:*" -> "1.0.1"
"workspace:^" -> "^1.0.1"
"workspace:~" -> "~1.0.1"

Setting a specific version takes precedence over the package’s package.json version,

"workspace:1.0.2" -> "1.0.2" // Even if current version is 1.0.1

Workspaces have a couple major benefits. Code can be split into logical parts. If one package relies on another, add it as a dependency in package.json. If package b depends on a, bun install will install your local packages/a directory into node_modules instead of downloading it from the npm registry. Dependencies can be de-duplicated. If a and b share a common dependency, it will be hoisted to the root node_modules directory. This reduces redundant disk usage and minimizes “dependency hell” issues associated with having multiple versions of a package installed simultaneously. Run scripts in multiple packages. You can use the --filter flag to run package.json scripts in multiple packages in your workspace, or --workspaces to run scripts across all workspaces. ​Share versions with Catalogs When many packages need the same dependency versions, catalogs let you define those versions once in the root package.json and reference them from your workspaces using the catalog: protocol. Updating the catalog automatically updates every package that references it. See Catalogs for details. ⚡️ Speed — Installs are fast, even for big monorepos. Bun installs the Remix monorepo in about 500ms on Linux. 28x faster than npm install 12x faster than yarn install (v1) 8x faster than pnpm install

Was this page helpful?

YesNoSuggest editsRaise issuebun infoPreviousCatalogsNext⌘IxgithubdiscordyoutubePowered byThis documentation is built and hosted on Mintlify, a developer documentation platform