English for Bun Workspaces

Bun’s built-in workspace support has made it a serious option for monorepo tooling, competing directly with pnpm and Turborepo setups. Talking about workspaces precisely — knowing the difference between a “linked package” and a “catalog dependency” — matters when you’re debugging why one app in the monorepo has a different version of a shared library than another. This guide covers the essential vocabulary.

Key Vocabulary

Workspace — in a monorepo, an individual package (an app or a shared library) that’s declared as part of the root package.json’s workspaces field, allowing Bun to manage its dependencies alongside its siblings. “We added the new ui package as a workspace so the web app and the admin app can both import it directly.”

Workspace protocol (workspace:*) — a special version specifier used in a package’s package.json to reference another workspace in the same monorepo, rather than a version published to a registry. “Use workspace:* for the internal ui package instead of pinning a version number — Bun will always resolve it to the local copy.”

Linked package — a workspace dependency that Bun symlinks into node_modules rather than downloading, so changes to the source package are immediately visible to whatever depends on it. “Since ui is a linked package, you don’t need to rebuild and republish it — edits show up in the app instantly.”

Catalog dependency — a centrally defined dependency version, declared once in the workspace root, that multiple packages can reference to guarantee they all use the same version. “We moved React into the dependency catalog so every app in the monorepo is forced to use the same version, instead of drifting apart.”

Hoisting — the process of installing shared dependencies once at the root node_modules rather than duplicating them inside every workspace, reducing install size and duplication. “Most of our dependencies get hoisted to the root, which is why deleting a single package’s node_modules folder doesn’t actually remove much.”

Workspace filter — a command-line option (bun run --filter) that scopes a script to run only in specific workspaces, useful for building or testing a subset of a large monorepo. “Use a workspace filter so CI only runs tests for the packages that actually changed, instead of the whole monorepo every time.”

Common Phrases

• “Is that dependency version coming from the catalog, or did someone pin it locally in that one package?”
• “Check whether the package is properly linked — if it’s not, you’re probably testing against a stale published version.”
• “Run the build with a workspace filter so we’re not rebuilding every app for a one-line change.”
• “This version mismatch is exactly why we moved shared dependencies into the catalog.”
• “Don’t forget to declare the new package as a workspace, or Bun won’t pick up its dependencies.”

Example Sentences

Explaining the monorepo setup to a new hire: “Everything under packages/ and apps/ is a workspace, so when you install dependencies at the root, Bun links the internal packages together automatically — you never need to npm link anything manually.”

Debugging a version mismatch: “The bug only reproduces in the admin app because it’s still pinned to an older version of the shared date library, while everything else pulls from the catalog. Let’s move it into the catalog so this can’t happen again.”

Describing CI performance improvements: “We cut CI time significantly by using workspace filters — pull requests that only touch the ui package no longer trigger a full rebuild and test run across every app in the monorepo.”

Professional Tips

• Say “linked” specifically when a workspace package resolves to local source code, not a published version — this distinction is crucial when debugging “it works in the package but not in the app” issues.
• Recommend the dependency catalog proactively in code review when you see the same dependency pinned to different versions across workspaces — it’s a common and easily preventable source of subtle bugs.
• Use workspace filters when describing CI or build optimizations; naming the mechanism specifically helps teammates replicate the approach elsewhere.
• Distinguish hoisting (an installation optimization) from linking (a resolution mechanism for internal packages) — conflating them leads to confused troubleshooting.

Practice Exercise

1. Explain, in two sentences, why using workspace:* is preferable to pinning a version number for an internal package.
2. Write a one-sentence PR description proposing to move a dependency into the shared catalog.
3. Describe how you’d use a workspace filter to speed up CI for a monorepo with twenty packages.