â—ŹChange8

v11.0.0-alpha.2

Breaking Changes
📦 pnpmView on GitHub →
⚠ 14 breaking✨ 11 features🔧 9 symbols

Summary

pnpm 9.x introduces pure ESM packaging, a bundled Node runtime, JSON‑based config output, camelCase keys, and V8‑binary store, while dropping Node 18/19 support and changing several CLI behaviours.

⚠️ Breaking Changes

  • `pnpm config get` without `--json` now outputs JSON instead of INI formatted text; scripts that parsed INI output must add `--json` or update parsing logic.
  • `pnpm config list` and `pnpm config get` (no argument) now hide auth‑related settings; any tooling expecting those settings must explicitly request them or read from rc files.
  • The package is now pure ESM; requiring it via CommonJS (`require('pnpm')`) will fail. Convert imports to ESM or add a wrapper.
  • pnpm no longer loads non‑auth and non‑registry settings from rc files; such settings must be moved to `pnpm-workspace.yaml`.
  • Support for Node.js v18 and v19 has been dropped; pnpm must be run on Node.js >=20.
  • `pnpm config get <array>` now prints a JSON array; previous plain‑text representation is no longer available.
  • The default `type` field in a newly created `package.json` (via `pnpm init`) is now `module` instead of `commonjs`; projects expecting CommonJS need to set `"type": "commonjs"` manually.
  • `pnpm config list` and `pnpm config get` now present top‑level keys in camelCase (except keys starting with `@` or `//`). Scripts relying on original kebab‑case keys must adapt.
  • The standalone executable now requires glibc 2.27 or newer; it will fail on older Linux distributions.
  • `pnpm config list` now prints a JSON object instead of INI formatted text.
  • `pnpm config get` and `pnpm config list` no longer load non‑camelCase options from `pnpm-workspace.yaml`.
  • Store and cache files are now binary V8‑serialized files; any external process that reads the JSON files will break.
  • `pnpm add -p` is now an alias for `--save-prod` (previously `--parseable`).
  • `pnpm add -d` is now an alias for `--save-dev` (previously `--loglevel=info`).

Migration Steps

  1. Add `--json` to any `pnpm config get` calls that previously relied on INI output, or update parsing to handle
  2. If you need auth settings, retrieve them directly from rc files or use `pnpm config get --json <key>`.
  3. Convert any `require('pnpm')` imports to ESM `import` statements, or add a compatibility wrapper.
  4. Move non‑auth/non‑registry configuration options from `.npmrc` or other rc files into `pnpm-workspace.yaml`.
  5. When initializing new projects, set `"type": "commonjs"` in `package.json` if you need CommonJS modules.
  6. Update scripts that reference configuration keys to use camelCase names.
  7. On Linux, ensure glibc version is at least 2.27 before using the standalone exe; otherwise use the npm‑installed version.
  8. Clear the pnpm store/cache after upgrading, or let pnpm ignore incompatible binary files.
  9. Replace usage of `pnpm add -p` and `-d` with the new meanings (`--save-prod` and `--save-dev`) or use the long option names.
  10. Rename any `.pnpmfile.js` to `.pnpmfile.mjs` and ensure it uses ESM syntax.

✨ New Features

  • `pnpm config get` now prints JSON for objects/arrays and raw values for primitives, providing consistent output.
  • `pnpm config list` and `pnpm config get` hide auth‑related settings by default, improving security.
  • pnpm is distributed as a pure ESM package.
  • The pnpm CLI is bundled with a specific Node.js version for its runtime, making it independent of the globally installed Node.
  • Support for lowercase short options in `pnpm add` (`-d`, `-p`, `-o`, `-e`).
  • Environment variables prefixed with `pnpm_config_` are now loaded into pnpm config and override `pnpm-workspace.yaml` values.
  • Global YAML configuration file `config.yaml` is supported for pnpm‑specific settings.
  • pnpmfiles can be written in ESM with the `.mjs` extension (`.pnpmfile.mjs`).
  • Runtime dependencies are always linked from the global virtual store.
  • Store and cache now use V8 binary serialization, improving read performance by ~23%.
  • Explicitly tell `npm` the path to the global `rc` config file.

🔧 Affected Symbols

pnpm config getpnpm config listpnpm initpnpm addpnpm-workspace.yamlconfig.yaml.pnpmfile.mjsglobal virtual storestore/cache binary files