Coordinating Version Bumps in a pnpm Monorepo with `pnpm version --workspace`

The manual versioning trap in monorepos

In a monorepo—a single repository containing multiple packages—keeping versions aligned by hand is a slow way to introduce bugs. You bump a shared library from 1.0.0 to 1.1.0, then hunt through dependent packages to update their workspace: references. Miss one, and CI fails on a dependency mismatch. The problem compounds as packages grow.

pnpm offers a narrower alternative: a workspace-aware version command that updates every declared package and rewrites internal dependency ranges in one step. It does not solve release orchestration, but it removes the mechanical editing that causes drift.

How pnpm version --workspace rewrites internal ranges

Semantic versioning (semver) uses a MAJOR.MINOR.PATCH scheme to signal compatibility. In a pnpm workspace, packages are listed in pnpm-workspace.yaml, and internal dependencies use the workspace: protocol—for example, "dep": "workspace:^1.0.0". That protocol tells pnpm to resolve the dependency to a local package rather than a registry entry.

When you run pnpm version <release> --workspace from the workspace root, pnpm applies the same version change to every package discovered by the workspace configuration. It also rewrites workspace: ranges so they point at the new versions. The command assumes every package follows semver and lives inside the declared workspace globs.

Worked example: bumping two packages together

Imagine a repository with two packages, pkg-a and pkg-b. pkg-b depends on pkg-a via "pkg-a": "workspace:^1.0.0". Both packages currently sit at 1.0.0.

From the repository root, run:

pnpm version minor --workspace

This requires write access to the files in the workspace and should be run in a clean working tree so the diff is reviewable. The minor placeholder can be patch, major, or an explicit version such as 2.0.0.

After the command completes, both package.json files should show 1.1.0, and pkg-b's dependency should read "pkg-a": "workspace:^1.1.0". To confirm the change across the workspace, run:

pnpm ls -r --depth=0

Expected check: the output lists every workspace package with the new version. If a package is missing from that list, it is not covered by the workspace globs.

Where the automation stops

The --workspace flag only touches packages that pnpm discovers through pnpm-workspace.yaml. A package in a subfolder that is not matched by the workspace patterns is ignored. If that package also carries a workspace: dependency, it will not be updated, creating silent version drift.

The feature also assumes the version lives in the standard version field of package.json. If a package stores its version in a custom field or relies on an external versioning tool, pnpm will not rewrite it. Those packages need manual updates or a separate release process.

Finally, the command does not update the lockfile by itself. After bumping versions, run:

pnpm install

Expected check: pnpm-lock.yaml records the new versions, and the install completes without resolution warnings. If the lockfile is not regenerated, CI may install stale metadata.

Verification and rollback in a release pipeline

Before merging, inspect the generated pnpm-lock.yaml to ensure the new versions are recorded. A quick sanity check is to run pnpm ls -r --depth=0 again and compare it against the pre-bump output.

Because pnpm version --workspace modifies files in place, treat it as a state-changing operation. The simplest rollback is to discard the changes in version control—for example, git checkout -- . in the workspace root—before committing. If the bump is already committed, revert the commit or manually restore the previous versions.

In CI, wire the command into your release pipeline after the version decision is made, then run pnpm install and your test suite before publishing. That sequence catches drift early and keeps the lockfile consistent with the manifests.