●Change8

Migrating to pnpm v12.0.0-beta.4

Version v12.0.0-beta.4 introduces 2 breaking changes. This guide details how to update your code.

Released: 8/3/2026

2
Breaking Changes
2
Migration Steps
10
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

`namedRegistries``pnpm-lock.yaml``ERR_PNPM_INVALID_PROXY``ERR_PNPM_MISSING_NAMED_REGISTRY``ERR_PNPM_RESERVED_NAMED_REGISTRY_NAME``pnpm licenses``pnpm sbom``@pnpm/exe``pnpm install``refToRelative`

Breaking Changes

●Issue #1

Projects using `namedRegistries` on pnpm 11.1.0–11.19.x are semi-breaking. The lockfile no longer records tarball URLs for named-registry packages; these are now recomputed from the `namedRegistries` setting on demand. To fix, commit the lockfile diff generated by a non-frozen install, which will re-key entries with registry-qualified names (e.g., `foo@work:1.0.0`). Ensure all collaborators are on this version or newer before updating the lockfile to prevent lockfile flipping.

●Issue #2

Named registry aliases that shadow reserved dependency specifier prefixes (e.g., `file`, `link`, `workspace`, `runtime`, `npm`, `jsr`) are now rejected with `ERR_PNPM_RESERVED_NAMED_REGISTRY_NAME` instead of being silently shadowed. To fix, rename your named registry alias to avoid conflicts with reserved prefixes.

Migration Steps

  1. 1
    If you use named registries, commit the lockfile diff generated by a non-frozen install to update entries to registry-qualified keys.
  2. 2
    If you use named registries and have aliases that shadow reserved dependency specifier prefixes, rename your named registry aliases to avoid conflicts.

Release Summary

This release addresses a critical security vulnerability in named registries and significantly improves performance for large and complex workspaces. It also introduces a new `npmjs:` alias for better control over registry resolution.

Need More Details?

View the full release notes and all changes for pnpm v12.0.0-beta.4.

View Full Changelog