Using pnpm workspace:* for Local Development and Versioned Releases

The Problem: Publishing Too Often or Not at All

You fix a bug in a shared UI package inside your monorepo, but the application that consumes it still runs the old code. You could publish a new version to the npm registry after every edit, but that forces every consumer to upgrade constantly and creates version churn for internal changes that are not ready for a release. The practical alternative is pnpm's workspace: protocol, which lets packages in the same monorepo reference each other by a version range instead of a fixed number.

A monorepo is a single repository that holds multiple packages. A workspace is one of those packages, installed together by pnpm. A registry is a public package server such as npm.

How workspace:* Resolves Dependencies

When package.json lists "@acorn/ui": "workspace:*", pnpm looks for @acorn/ui in the directories declared in the root pnpm-workspace.yaml before it contacts any registry. If it finds a match, it links the local package into the consumer's node_modules. Changes to the local package take effect immediately, with no publish step required.

Worked Example: A Two-Package Monorepo

Repository layout:

my-monorepo/
├── pnpm-workspace.yaml
├── package.json
└── packages/
    ├── ui/
    │   └── package.json   # name: @acorn/ui
    └── app/
        └── package.json   # name: @acorn/app

Root pnpm-workspace.yaml:

packages:
  - 'packages/*'

In packages/app/package.json, reference the local UI package:

{
  "name": "@acorn/app",
  "dependencies": {
    "@acorn/ui": "workspace:*"
  }
}

Run pnpm install in the repository root; this requires write access to node_modules. pnpm links the local @acorn/ui package into packages/app/node_modules without downloading it from a registry. Edit packages/ui, restart the app, and the change appears without a new version number.

Verify the link with:

pnpm ls @acorn/ui --dir packages/app

If the command fails, confirm that packages/ui is listed in pnpm-workspace.yaml and that its package.json name matches the dependency key exactly.

The Publishing Trade-Off

You cannot publish workspace:* to a public registry. A consumer installing your package from npm cannot resolve the workspace: prefix, so the install fails. Before publishing @acorn/ui, decide whether dependent packages will also be public.

A practical workflow:

1. Develop with workspace:* across all internal packages.
2. When @acorn/ui is ready for release, bump its version in packages/ui/package.json.
3. If @acorn/app will also be published, update packages/app/package.json from "workspace:*" to a pinned range such as "@acorn/ui": "^1.0.0". If app stays private, leave it as workspace:*.
4. Run pnpm install again to update pnpm's lockfile, then publish.

For private monorepos that never publish to npm, you can keep workspace:* indefinitely. For hybrid repositories, treat workspace:* as a development-only alias.

Limitations and Verification

• Version requirement: workspace: requires pnpm 7.0 or newer. Run pnpm -v in the repository root; upgrade if the output is below 7.0.
• Circular dependencies: If @acorn/ui depends on @acorn/app and @acorn/app depends on @acorn/ui, pnpm reports a resolution failure. Move shared code into a third package to break the cycle.
• Disk usage: pnpm stores packages once in a global store and hardlinks them, so local workspace packages do not create full copies in each consumer's node_modules.

Check that the workspace link is active:

ls -la packages/app/node_modules/@acorn/ui

The entry should point to the local workspace package rather than a downloaded archive. If it points to the pnpm store instead, the workspace field may be missing or misnamed.

Actionable Closing

Add pnpm-workspace.yaml to your monorepo root, list your package directories, and switch internal references to workspace:*. Run pnpm install and verify with pnpm ls. Before any public release, pin the dependency to a real version so registry consumers can install it safely.

To undo the change, replace workspace:* entries with pinned versions in package.json and run pnpm install again.