v12.0.0
Breaking Changes📦 pnpmView on GitHub →
⚠ 2 breaking✨ 6 features🐛 2 fixes🔧 6 symbols
Summary
This release introduces canonical dependency cycle breaking for consistent lockfiles and enhances Git dependency handling by treating them as identities. It also adds support for project-aware global bins and the ability to manage other package managers.
⚠️ Breaking Changes
- Projects with unrecognized settings in `pnpm-workspace.yaml` will now fail the command with `ERR_PNPM_UNRECOGNIZED_WORKSPACE_SETTINGS` if a pnpm version is pinned that satisfies the setting. Previously, unrecognized settings were ignored silently. To fix, remove or correct unrecognized settings in `pnpm-workspace.yaml`.
- Under `engineStrict`, installs will now fail when an incompatible package is reached through a regular `dependencies` edge, even if it's part of an optional dependency subtree. Previously, this would result in an install-check warning. To fix, ensure all direct dependencies meet the `engineStrict` requirements.
Migration Steps
- To access private hosted Git repositories over SSH, configure git's URL rewriting globally: `git config --global url."git@github.com:".insteadOf https://github.com/`.
- Review and correct any unrecognized settings in your `pnpm-workspace.yaml` file to avoid command failures or warnings.
- Configure the `globalShims` setting in `pnpm-workspace.yaml` or use `PNPM_SHIM_BYPASS=1` to manage project-aware global bins.
- When using `pnpm dlx` (or `pnx`) with package managers, specify the desired version or package directly (e.g., `pnx yarn@4 install`, `pnx node@22`).
✨ New Features
- Git dependencies on known hosts (GitHub, GitLab, Bitbucket) are now treated as identities, always resolving through the host's canonical HTTPS URL. This removes network probing and ensures consistent transport. Private repositories can be accessed over SSH by configuring git's URL rewriting (e.g., `git config --global url."git@github.com:".insteadOf https://github.com/`).
- Unrecognized settings in `pnpm-workspace.yaml` are now reported as errors or warnings, rather than being ignored silently. This helps catch typos and ensures settings are intentional.
- Dependency cycles are now broken canonically during peer resolution, leading to byte-identical lockfiles regardless of installation order. This improves performance and reduces lockfile size for cyclic dependencies.
- `packageImportMethod: auto` now prioritizes hardlinks over cloning on Linux for faster `node_modules` materialization.
- Globally installed bins can now follow the project they are run in via the `globalShims` setting. This allows projects to use specific versions of tools like Node.js, Deno, or Bun without shell hooks, with configurable trust prompts.
- pnpm can now install and manage other package managers (npm, Yarn Classic, Yarn Berry, Bun). This is used to prepare git-hosted dependencies with their specified package manager and to run commands via `pnpm dlx` (e.g., `pnx yarn@4 install`).
🐛 Bug Fixes
- Dependency cycles are now broken canonically during peer resolution, fixing issues where lockfiles could differ based on installation order and where peer resolution verdicts were wrongly reused [#13846, #13865].
- Under `engineStrict`, installs now correctly fail for incompatible packages in regular `dependencies` edges, addressing a previous behavior where only a warning was emitted [#13286].