This page describes how Bun's package manager handles workspaces and monorepo configurations. Workspaces allow multiple packages to coexist in a single repository, with automatic linking and shared dependency management. Bun's implementation focuses on high-performance resolution, catalog support for version synchronization, and cross-platform binary compatibility.
For information about the general package installation process, see Package Manager. For dependency resolution mechanics, see Dependency Resolution.
Workspaces are configured in the root package.json through the workspaces field, which accepts an array of glob patterns. Bun supports both positive patterns (to include directories) and negative patterns (to exclude directories).
The workspaces array is parsed during lockfile initialization. Bun supports negative patterns using the ! prefix, allowing fine-grained control over which directories are treated as workspace members test/cli/install/bun-workspaces.test.ts139-146
Sources:
Bun discovers workspace packages by evaluating glob patterns against the filesystem. Discovered packages are indexed by name hash and stored in the lockfile structures.
The workspace_paths map stores the filesystem path to each workspace package, while workspace_versions stores the semantic version declared in each workspace's package.json src/install/lockfile.zig21-22 Workspace packages are assigned a PackageID, which is a u32 index src/install/install.zig95
Sources:
When resolving dependencies, Bun checks if a workspace package can satisfy a version requirement before querying the npm registry. This allows local development without publishing.
Dependencies in Bun are categorized by their Behavior bitfield, which tracks if a dependency originated in dependencies, devDependencies, optionalDependencies, or peerDependencies src/install/dependency.zig37 This is crucial for workspaces where devDependencies in the root are treated differently than in member packages src/install/install.zig171-175
Sources:
Bun supports "Catalogs," a feature for monorepos to define shared dependency versions in the root package.json or bunfig.toml. This prevents version drift across multiple workspace packages.
When a dependency version is specified as catalog:default or catalog:name, Bun looks up the version in the catalogs map within the Lockfile src/install/lockfile.zig29
Sources:
Bun includes a high-performance package.json editor for programmatic dependency updates, such as during bun add or bun remove.
The PackageJSON struct in src/resolver/package_json.zig handles the parsing and representation of these files. It includes mappings for scripts, dependencies, and browser field redirects src/resolver/package_json.zig21-69
DependencyMap: An ArrayHashMap storing dependency names and their associated Dependency metadata src/resolver/package_json.zig9-19SideEffects: Handles the sideEffects field, supporting boolean, array of files, or glob patterns for tree-shaking optimization src/resolver/package_json.zig115-127Sources:
Bun handles executable binaries by creating symlinks (Unix) or shims (Windows) in the .bin directory.
The Bin struct in src/install/bin.zig normalizes the bin field from package.json, which can be a single file path, a directory, or a map of names to paths src/install/bin.zig1-11
Tag.file: Single binary mapping to the package name src/install/bin.zig15Tag.map: Multiple named binaries src/install/bin.zig21-27Bun ensures that workspace binaries are correctly linked into the root node_modules/.bin so they are available to all workspace members. This is verified in tests using toHaveBins and toBeWorkspaceLink test/cli/install/bun-install.test.ts31-43
Sources:
In a workspace environment, lifecycle scripts (like postinstall) are executed according to the dependency graph. Bun tracks these in the Lockfile.Scripts struct src/install/lockfile.zig54-75
preinstall, install, postinstall, preprepare, prepare, postprepare src/install/lockfile.zig58-65Entries (ArrayLists of strings) and executed by the RunCommand src/install/lockfile.zig56-74Sources:
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.