v12.0.0-rc.7

Breaking Changes

📅 Aug 18, 2026📦 pnpmView on GitHub →

⚠ 4 breaking✨ 5 features🐛 6 fixes⚡ 1 deprecations🔧 22 symbols

Summary

This release introduces significant improvements to registry configuration and resolution, including per-registry metadata support and enhanced `pnpr` protocol features. It also refines virtual store management with the new `virtualStoreType` setting.

⚠️ Breaking Changes

The `node_modules/.modules.yaml` file no longer records registries an install resolved from. This file is dropped on the first install that rewrites it. Previously, this file could cause installs to use outdated registry configurations.
The `registries` setting in `pnpm-workspace.yaml` now requires a new structure where each registry is keyed by its URL. The older map of `<scope>: <url>` strings is still supported for backward compatibility, but new configurations should adopt the URL-keyed structure.
The `pnpr` resolve and verify-lockfile request bodies have changed. Clients and servers must be on matching versions. The protocol is still experimental and unversioned.
The `pnpr` resolve request now carries the client's `resolutionMode`. Servers older than their client will ignore this field and default to `highest` resolution mode. The protocol is still experimental and unversioned.

Migration Steps

Update the `registries` configuration in `pnpm-workspace.yaml` to the new URL-keyed structure if you are using custom registries with specific layouts or scopes.
Ensure that both your pnpm client and any pnpr servers you use are on matching versions due to changes in the resolve and verify-lockfile request bodies and the addition of `resolutionMode` to the resolve request.
If you were using `namedRegistries`, migrate to using the `prefix` field within the `registries` setting.
If you were using `enableGlobalVirtualStore`, consider migrating to the new `virtualStoreType` setting for explicit control over the virtual store location.

✨ New Features

Added `virtualStoreType` setting (`global` or `project`) to explicitly define the location of the virtual store. This replaces and takes precedence over `enableGlobalVirtualStore`.
Registries can now declare if their abbreviated metadata carries the `time` field, allowing `resolutionMode: time-based` to optimize metadata fetching.
The `registries` setting now supports `serverType` (e.g., `npm`, `artifactory`) to correctly lay out tarball URLs, enabling omission from `pnpm-lock.yaml`.
The `registries` setting now allows defining `scopes` and `prefix` for each registry.
When `enableGlobalVirtualStore` is on, spawned processes now receive `NODE_PATH` and `NODE_OPTIONS` for improved ESM import resolution and phantom package support.

🐛 Bug Fixes

Previously, `pnpm list`, `pnpm why`, and single-project installs would incorrectly use registry information from `node_modules/.modules.yaml` even if the project's registry configuration had changed. This is now fixed, and these commands use the project's configured registries.
Projects with changed registry configurations were still being read through old ones due to `node_modules/.modules.yaml`. This is now fixed.
A pnpr server previously could not resolve scoped dependencies from registries they were routed to if they were not the default or prefix-addressed registry. This is now fixed.
A registry declared in a request was previously refused if it was not on the server's allowlist, even if the resolve did not reach it. This is now fixed, with the boundary moving to the fetch itself.
The `resolutionMode` was not being sent to pnpr servers, causing them to default to `highest` resolution. This is now fixed, with the client's `resolutionMode` being sent.
A pnpr server previously did not correctly handle scoped packages from registries like Artifactory where the scope is repeated in the tarball filename. This is now fixed by the `serverType: artifactory` declaration.

⚡ Deprecations

`namedRegistries` is deprecated in favor of the `prefix` field within the `registries` setting.