Skip to content

Lesson 28 ยท Monorepos

Workspace Protocol and Local Linking

Reference sibling packages with the workspace protocol in Yarn and pnpm, use * ranges in npm, see how versions are rewritten on publish, and link packages outside a monorepo.

Inside a monorepo, @acme/web depends on @acme/ui. But which version of @acme/ui? The one on the registry, or the one in the next folder? If you write "@acme/ui": "^0.3.0", the manager is free to fetch a published copy that may be older than your local changes, and your "edit and see it instantly" loop is gone. The workspace protocol removes the ambiguity: it means "always use the local one".

This lesson covers the workspace: protocol, what npm does instead, how local versions are rewritten when you publish, the catalog: idea for shared versions, and npm link for packages outside a workspace. Snippets are read-only; the runnable examples implement the rewrite and linking logic in plain Node.js.

Three ways to say "use the local package"

Manager Spelling Notes
pnpm "@acme/ui": "workspace:*" Fails if no workspace matches, so a typo never falls back to the registry
Yarn Berry "@acme/ui": "workspace:^" Same protocol; workspace:*, workspace:^, workspace:~ allowed
npm "@acme/ui": "*" or a matching range such as "^0.3.0" npm links the workspace only if its version satisfies the range; otherwise it falls back to the registry

The npm behaviour is the subtle one. If packages/ui is at version 0.3.0 and the web app asks for ^0.2.0, npm quietly downloads 0.2.x from the registry instead of linking. Check with npm ls @acme/ui: a linked workspace shows -> ./packages/ui.

JSON
{
  "name": "@acme/web",
  "dependencies": {
    "@acme/ui": "workspace:*",
    "@acme/utils": "workspace:^"
  }
}

(Yarn and pnpm; npm users write * or a satisfied range instead.)

What happens at publish time

The workspace: protocol is not valid on the registry; a consumer cannot resolve it. So when you publish, Yarn and pnpm replace it with a real version inside the tarball's package.json:

In your repo In the published tarball (ui is 0.3.0)
workspace:* 0.3.0
workspace:^ ^0.3.0
workspace:~ ~0.3.0
workspace:^0.2.0 ^0.2.0 (the range after the colon is kept)

npm does not have the protocol, so its * stays * after publish, which is usually not what you want. That is a strong practical reason for pnpm or Yarn in publishable monorepos (or for a release tool that rewrites ranges for npm).

Node.js Stand-in: rewrite workspace: ranges before publishing

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.

Catalogs: one version for many workspaces

In a big monorepo thirty packages might all depend on react and typescript. Keeping thirty ranges in sync is error-prone. pnpm (and Yarn Berry, in a slightly different form) offers catalogs: a single list of named versions in the workspace config, referenced with catalog:.

YAML
# pnpm-workspace.yaml
packages: ["apps/*", "packages/*"]
catalog:
  react: ^19.0.0
  typescript: ~5.8.0
JSON
{ "dependencies": { "react": "catalog:" } }

Upgrading React is now a one-line change, and the published manifests get the concrete range substituted, just like workspace:. With npm the usual alternative is a shared range kept in sync by a tool or by overrides (see overrides).

Linking packages outside a workspace

Sometimes the package you want to test lives in another repository: you are fixing a bug in a library and want to try it in your app before publishing. That is what linking is for.

Terminal
# In the library folder: register it globally
cd ~/code/my-lib && npm link

# In the app folder: use the registered copy
cd ~/code/my-app && npm link my-lib

# Undo
npm unlink my-lib

Under the hood it makes two symlinks: one from the global node_modules to the library folder, and one from the app's node_modules/my-lib to that. pnpm uses pnpm link --global (or pnpm link ../my-lib); Yarn Berry uses yarn link ../my-lib, which adds a portal: or link: resolution to the manifest.

Pitfalls of linking:

  • Two copies of a peer dependency. If the linked library resolves react from its own node_modules, the app ends up with two Reacts and hooks break ("Invalid hook call"). Fix by linking react from the app into the library, or by adding a bundler resolve.alias/preserveSymlinks setting.
  • Install wipes the links. A later npm install may remove the link; re-run npm link my-lib.
  • Build output. You link a folder, so the library must be built (dist/ present) unless the app compiles its source.
  • A file:../my-lib dependency copies instead of links in npm for tarballs but links for directories; read your manager's docs before relying on it.

The alternative to linking is to publish a pre-release to a next tag, or npm pack the library and install the tarball in the app, which tests exactly what users will receive.

The next stand-in shows the difference between a linked directory and a copy, which is the root of most "my change does not show up" bugs.

Node.js Stand-in: a symlink follows edits, a copy does not

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.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does workspace:* guarantee in pnpm or Yarn?

    The protocol means the local workspace package, and install fails if none matches, so there is no silent registry fallback.
  2. 2. A package at 0.3.0 is referenced as workspace:^ . What appears in the published manifest?

    Yarn and pnpm replace the protocol with the real version prefixed by the same operator when packing.
  3. 3. Why might npm download a registry copy of a sibling workspace?

    npm links a workspace only when its version satisfies the range; otherwise it resolves the range from the registry.
  4. 4. What is a common problem when linking a library that has a peer dependency such as react?

    The linked folder resolves its own node_modules, so peers can duplicate. Make both sides resolve the same copy.

Summary

  • workspace: (pnpm, Yarn) forces local resolution; npm uses * or a satisfied range and can silently fall back to the registry.
  • Yarn and pnpm rewrite workspace: and catalog: specs to real ranges when packing.
  • catalog: keeps shared versions in one place.
  • npm link, pnpm link and yarn link connect a package from another repository by symlink; beware duplicate peers.
  • Packing a tarball is the most faithful local test of what users receive.

Next: Filtering and Task Orchestration