Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 39 ยท Package Manager and Scripts

Workspaces and Catalogs

Build a monorepo with Bun workspaces - package globs, the workspace protocol, shared dependencies, catalogs for one version of a library, filtered scripts, installs and publishing.

As a project grows you often split it into several packages that live in one repository: a web app, an API, a shared library of types and helpers. This layout is called a monorepo, and the feature that makes it work is workspaces. Bun supports workspaces in package.json, links local packages to each other without publishing them, installs all dependencies in one pass, and lets you run scripts across packages. This lesson builds a small monorepo and shows catalogs, which keep a dependency version identical across every package.

The layout

TEXT
my-monorepo/
โ”œโ”€โ”€ package.json          (root, private)
โ”œโ”€โ”€ bun.lock              (one lockfile for everything)
โ”œโ”€โ”€ packages/
โ”‚   โ”œโ”€โ”€ shared/
โ”‚   โ”‚   โ”œโ”€โ”€ package.json  (name: @acme/shared)
โ”‚   โ”‚   โ””โ”€โ”€ src/index.ts
โ”‚   โ”œโ”€โ”€ api/
โ”‚   โ”‚   โ”œโ”€โ”€ package.json  (name: @acme/api)
โ”‚   โ”‚   โ””โ”€โ”€ src/index.ts
โ”‚   โ””โ”€โ”€ web/
โ”‚       โ”œโ”€โ”€ package.json  (name: @acme/web)
โ”‚       โ””โ”€โ”€ src/index.ts
โ””โ”€โ”€ node_modules/

The root package.json declares where the packages are:

JSON
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["packages/*"],
  "devDependencies": {
    "typescript": "^5.6.0"
  }
}

"private": true is required: the root is never published. Entries in workspaces are folder paths or globs. Every matching folder that holds a package.json becomes a workspace package. You can also exclude folders with ! patterns, for example "!packages/legacy".

Running bun install once, at the root, installs the dependencies of every package, shares what they have in common, and writes a single bun.lock. You do not run installs inside the sub-packages.

Depending on a sibling

Package @acme/api uses @acme/shared. In packages/api/package.json:

JSON
{
  "name": "@acme/api",
  "version": "0.1.0",
  "dependencies": {
    "@acme/shared": "workspace:*",
    "hono": "^4.6.0"
  }
}

The version workspace:* means "use the copy in this repository, whatever its version". Bun links it, so node_modules/@acme/shared points to packages/shared. Edit the shared code and the API sees the change immediately, with no publish and no rebuild if the package exports TypeScript source.

You can write workspace:^ or workspace:~; when the package is published these are replaced by real version ranges (^0.1.0), so the published package is valid on the registry. Plain * or a version also works, but workspace: states intent and fails loudly if the package is missing.

TypeScript
// packages/api/src/index.ts
import { formatPrice } from "@acme/shared";

console.log(formatPrice(1999));

For this to work, packages/shared/package.json needs an entry point, for example "main": "src/index.ts" or "exports": "./src/index.ts". Bun runs the TypeScript source directly, so a shared library needs no build step during development.

Discovering workspaces

The glob step is the heart of workspace support: find folders that contain a package.json. This runnable stand-in builds a throw-away monorepo in a temporary folder and finds the packages the way a package manager does:

Node.js Stand-in: discover workspace packages from a glob (Node 24)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Running scripts across packages

Use --filter with bun run:

Terminal
bun run --filter "*" build               # every workspace package
bun run --filter "@acme/*" test          # by name pattern
bun run --filter "./packages/api" dev    # by folder
bun run --filter "!@acme/web" lint       # everything except web

Bun runs the script in each matching package that defines it, in dependency order where relevant, and prefixes output with the package name so interleaved logs stay readable. Scripts that run forever (dev servers) can run in parallel this way, which is a common setup: one command starts API and web together.

Installs can be filtered as well:

Terminal
bun install --filter "@acme/api"      # install only what the API needs

This is useful in Docker builds that ship a single service from a large repository.

You can also run commands in one package without a filter by changing directory (bun run --cwd packages/api dev) or by using a root script that delegates:

JSON
{
  "scripts": {
    "dev": "bun run --filter '*' dev",
    "typecheck": "tsc --noEmit -p packages/api && tsc --noEmit -p packages/web"
  }
}

Catalogs: one version for all

In a monorepo, react might appear in three packages. If they list different versions, bugs appear in ways that are painful to trace. Catalogs let you write the version once in the root and reference it by name everywhere else.

Root package.json:

JSON
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "react": "^19.1.0",
      "typescript": "^5.6.0"
    },
    "catalogs": {
      "testing": {
        "vitest": "^3.0.0",
        "@testing-library/react": "^16.0.0"
      }
    }
  }
}

In a package:

JSON
{
  "name": "@acme/web",
  "dependencies": {
    "react": "catalog:",
    "@acme/shared": "workspace:*"
  },
  "devDependencies": {
    "typescript": "catalog:",
    "vitest": "catalog:testing"
  }
}
  • "catalog:" refers to the default catalog.
  • "catalog:testing" refers to a named group in catalogs.

To upgrade React everywhere, change one line in the root and run bun install. When a package is published, catalog: entries are replaced with the real ranges, so consumers never see the placeholder. Notice that the shape of workspaces changed from an array to an object; this is required to add catalogs.

Here is a stand-in that resolves catalog: references the same way:

Node.js Stand-in: resolve catalog: references (runs on Node 24)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

How packages are linked

By default Bun installs workspace dependencies in a hoisted layout: shared third-party packages are placed in the root node_modules, and each workspace package gets its own node_modules only for conflicting versions, which is the traditional npm and Yarn shape. Newer Bun releases also offer an isolated linker (like pnpm's), where each package sees only the dependencies it declares, which catches missing declarations. Select it in bunfig.toml:

TOML
[install]
linker = "isolated"   # or "hoisted"

Isolated installs are stricter and more correct; hoisted installs are more compatible with older tools. If a package works on your machine but fails elsewhere with "cannot find module", an undeclared dependency hidden by hoisting is the usual suspect.

Publishing workspace packages

Publishing each package replaces workspace: and catalog: specifiers with real versions:

Terminal
cd packages/shared
bun publish --dry-run     # check what would be uploaded
bun publish

bun pm pack produces the tarball so you can inspect it first. Remember to bump version in the package before publishing; tools such as Changesets automate that across many packages.

Common mistakes

  • Running bun install inside a sub-package. Run it at the root.
  • Forgetting private: true on the root. The root must not be publishable.
  • Declaring a sibling with a normal version and getting a copy from the registry instead of the local one. Use workspace:*.
  • Importing a package that is not in dependencies and relying on hoisting. Declare every import.
  • Different TypeScript versions per package. Use a catalog.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the dependency version "workspace:*" mean?

    workspace:* links to the sibling package in the monorepo.
  2. 2. Where do you run bun install in a monorepo?

    One install at the root handles every workspace package and writes a single bun.lock.
  3. 3. What does the dependency react: catalog: in a package mean?

    catalog: refers to the default catalog in the root workspaces configuration, keeping versions consistent.
  4. 4. Which command runs the build script in every package whose name starts with @acme/?

    bun run --filter selects workspace packages by name or path pattern.

Summary

  • "workspaces": ["packages/*"] in a private root package.json turns matching folders into linked packages with one lockfile.
  • Depend on siblings with workspace:* (or ^/~); shared TypeScript source needs no build step in development.
  • bun run --filter runs scripts across packages, and bun install --filter limits installs.
  • Catalogs (catalog: and named catalog:name) keep dependency versions identical across the repository.
  • Choose a hoisted or isolated linker in bunfig.toml; declare every dependency you import.

Next: Overrides, Patches and Registries