●Change8

v11.0.0-rc.0

Breaking Changes
📦 pnpmView on GitHub →
⚠ 12 breaking✨ 11 features🐛 2 fixes⚡ 1 deprecations🔧 19 symbols

Summary

This major release enforces Node.js 22+ compatibility, transitions pnpm to pure ESM, and significantly enhances security by enabling supply-chain protection defaults. It also overhauls configuration handling, moving most settings out of .npmrc, and introduces a new SQLite-backed store index for faster installations.

⚠️ Breaking Changes

  • Node.js versions 18, 19, 20, and 21 are no longer supported. Users must upgrade to Node.js 22+.
  • pnpm is now pure ESM; this may break scripts relying on CommonJS module loading mechanisms.
  • The standalone executable now requires glibc 2.27 or newer.
  • Deprecated build dependency settings (`onlyBuiltDependencies`, `onlyBuiltDependenciesFile`, `neverBuiltDependencies`, `ignoredBuiltDependencies`, and `ignoreDepScripts`) have been removed. They must be replaced by the `allowBuilds` setting.
  • The `allowNonAppliedPatches` setting has been removed and replaced by `allowUnusedPatches`.
  • Patch application failures now throw an error instead of being ignored (removal of `ignorePatchFailures`).
  • Global installs now use the global virtual store by default, storing packages in `{storeDir}/links`. This changes how global packages are isolated and managed.
  • `pnpm link <pkg-name>` no longer resolves packages from the global store; only relative or absolute paths are accepted (e.g., use `pnpm link ./foo`).
  • `pnpm link --global` is removed. Use `pnpm add -g .` instead to register local package bins globally.
  • `pnpm link` (with no arguments) is removed. Use `pnpm link <dir>` with an explicit path.
  • pnpm no longer reads most settings from `.npmrc`. Only auth and registry settings are read from `.npmrc`. All other configuration (like `hoistPattern`, `nodeLinker`) must be moved to `pnpm-workspace.yaml` or `~/.config/pnpm/config.yaml`.
  • Environment variables for configuration must now use the `pnpm_config_*` prefix; old `npm_config_*` variables are no longer read for configuration purposes.

Migration Steps

  1. Upgrade your Node.js environment to version 22 or higher.
  2. If you relied on CommonJS loading for pnpm scripts, update them to handle pure ESM.
  3. If you used deprecated build dependency settings (`onlyBuiltDependencies`, etc.), replace them with the `allowBuilds` map in your configuration.
  4. If you need to opt out of the 1-day minimum release age protection, set `minimumReleaseAge: 0` in `pnpm-workspace.yaml`.
  5. Move configuration settings other than auth/registry (e.g., `hoistPattern`, `nodeLinker`) from `.npmrc` files to `pnpm-workspace.yaml` or `~/.config/pnpm/config.yaml`.
  6. Ensure environment variables for configuration use the `pnpm_config_*` prefix.
  7. If you use global packages, run `pnpm setup` to update your shell configuration to point to the new location for globally installed binaries.
  8. Review usage of `pnpm link`. If linking local packages, use explicit paths (e.g., `pnpm link ./my-package`).
  9. If you relied on `pnpm install -g` (no arguments), switch to using `pnpm add -g <pkg>`.

✨ New Features

  • Supply-chain protection is enabled by default: `minimumReleaseAge` defaults to 1 day (24 hours), preventing resolution of newly published packages immediately.
  • Supply-chain protection default setting `blockExoticSubdeps` is now `true` by default.
  • The `allowBuilds` setting is introduced to control which packages are allowed to run build scripts.
  • Global installs (`pnpm add -g`) now use an isolated global virtual store, giving each global installation its own `package.json`, `node_modules`, and lockfile.
  • New commands added: `pnpm ci`, `pnpm sbom`, `pnpm clean`, `pnpm peers check`, and `pnpm runtime set`.
  • Short aliases `pn` and `pnx` are introduced for `pnpm` and `pnpm exec` respectively.
  • Support for ESM `.pnpmfile.mjs` files.
  • `pnpm audit --fix=update` now fixes vulnerabilities by updating packages in the lockfile instead of using overrides.
  • Significant performance improvements via undici with Happy Eyeballs, direct-to-CAS writes, skipped staging directory, pre-allocated tarball downloads, and an NDJSON metadata cache.
  • The package store index is upgraded to v11, using SQLite for metadata storage, which reduces filesystem syscalls and speeds up installation.
  • Bundled package manifests (name, version, scripts, etc.) are now stored directly in the store index, eliminating the need to read `package.json` from the CAS during resolution.

🐛 Bug Fixes

  • The default value for `optimisticRepeatInstall` is changed to `true`.
  • The default value for `verifyDepsBeforeRun` is changed to `install`.

Affected Symbols

pnpm CLI (general)pnpm publish flowpnpm loginpnpm logoutpnpm viewpnpm deprecatepnpm unpublishpnpm dist-tagpnpm versionpnpm add -gpnpm remove -gpnpm update -gpnpm list -gpnpm linkpnpm link --global.npmrc (configuration reading)pnpm-workspace.yaml (configuration reading)config.yaml (new configuration file)npm passthrough commands

⚡ Deprecations

  • The `.pnpmfile.cjs` file is now superseded by `.pnpmfile.mjs` if both exist; `.pnpmfile.mjs` takes priority.