●Change8

v11.22.0

Breaking Changes
📦 pnpmView on GitHub →
⚠ 2 breaking✨ 5 features🐛 7 fixes⚡ 1 deprecations🔧 37 symbols

Summary

This release introduces performance improvements for Node.js runtime resolution and enhances the `pnpm deploy` command. It also refines configuration handling and introduces new settings for cache management and pruning.

⚠️ Breaking Changes

  • Configuration settings like `configDir`, `pnpmHomeDir`, `stateDir`, `workspaceDir`, `globalPkgDir`, `rootProjectManifestDir`, `bin`, `dir`, `globalBinDir`, `globalDir`, `npmrcAuthFile`, `userconfig` can no longer be set within a project's `pnpm-workspace.yaml`. These settings are now resolved from the environment. pnpm will warn if these are found in `pnpm-workspace.yaml`. Use dedicated flags like `--dir` and `--global-dir` instead.
  • `pnpm config set` will now refuse to write settings to `pnpm-workspace.yaml` that pnpm does not read from there (e.g., `configDir`, `pnpmHomeDir`, `stateDir`). It will fail with `ERR_PNPM_CONFIG_SET_NOT_A_PROJECT_SETTING` and indicate where the setting should belong. Existing settings in `pnpm-workspace.yaml` can still be deleted with `pnpm config delete`.

Migration Steps

  1. If you were using settings like `configDir`, `pnpmHomeDir`, `stateDir`, `workspaceDir`, `globalPkgDir`, `rootProjectManifestDir`, `bin`, `dir`, `globalBinDir`, `globalDir`, `npmrcAuthFile`, or `userconfig` in your `pnpm-workspace.yaml`, you will need to remove them and manage these settings via environment variables or dedicated command-line flags.
  2. Consider enabling the new `minimumReleaseAgeExcludePrune` setting to automatically clean up your `pnpm-workspace.yaml`.
  3. If you use `pnpm deploy`, be aware that workspace dependencies will now be injected into the deploy directory by default.

✨ New Features

  • Added `pnpm cache path` to display the directory pnpm uses for its metadata cache, useful for CI caching.
  • Introduced `minimumReleaseAgeExcludePrune` setting to automatically prune `minimumReleaseAgeExclude` entries in `pnpm-workspace.yaml` when versions are no longer resolvable.
  • Resolving Node.js runtime versions (`devEngines.runtime` / `runtime:` specifiers) is now significantly faster due to caching of per-version release metadata.
  • `pnpm deploy` now injects workspace dependencies into the deploy directory, making it self-contained.
  • Global installs now use atomic switches, pointing command shims to a stable per-package link instead of a specific install directory, improving reliability during updates.

🐛 Bug Fixes

  • Fixed intermittent `ERR_PNPM_ENOENT` and `ERR_PNPM_ENOTEMPTY` errors during installation with `nodeLinker: hoisted` when using `patchedDependencies` in workspaces.
  • Corrected `pnpm audit --fix` and `pnpm audit --fix update` to not add `minimumReleaseAgeExclude` entries for patched versions published before the `minimumReleaseAge` cutoff.
  • Fixed an issue where `pnpm add <pkg>@<version>` and `pnpm update <pkg>@<version>` under a non-manual `catalogMode` would silently drop requests when the catalog entry was a range that covered the requested version but resolved to a different one.
  • Resolved a bug where a project not involved in a catalog entry move would incorrectly keep the old version, leading to catalog entries resolving to multiple versions.
  • Fixed `pnpm add <pkg>@<version>` and `pnpm update <pkg>@<version>` under `catalogMode: strict` to no longer fail with `ERR_PNPM_CATALOG_VERSION_MISMATCH` when the catalog entry is a range that satisfies the wanted version.
  • Fixed an issue where an in-place override update in the lockfile would not correctly update the overridden package when it was also a catalog entry, and vice-versa.
  • Fixed `pnpm deploy --no-optional` to not write a lockfile whose snapshots reference optional dependencies that the deploy directory does not contain.

Affected Symbols

`pnpm cache path``--config.config-dir``--config.pnpm-home-dir``--config.workspace-dir``--config.global-pkg-dir``--config.root-project-manifest-dir``pnpm config set``pnpm config delete``minimumReleaseAgeExcludePrune``cleanupUnusedCatalogs``catalogPrune``configDir``pnpmHomeDir``stateDir``bin``dir``globalBinDir``globalDir``npmrcAuthFile``userconfig``workspaceDir``cacheDir``storeDir``devEngines.runtime``runtime:` specifiers`pnpm audit --fix``pnpm audit --fix update``minimumReleaseAgeExclude``pnpm add <pkg>@<version>``pnpm update <pkg>@<version>``catalogMode``catalogMode: strict``pnpm install``pnpm deploy``injectWorkspacePackages``dedupeInjectedDeps``pnpm deploy --no-optional`

⚡ Deprecations

  • The setting `cleanupUnusedCatalogs` has been renamed to `catalogPrune`. While `cleanupUnusedCatalogs` still works, `catalogPrune` takes precedence if both are set.