Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 36 ยท 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