KN-020Mục đích: Công cụ

pnpm 10 → 11 migration

#pnpm#corepack#nodejs
Kiểm mục
  • Require Node.js ≥ 22 before upgrading pnpm
  • Pin pnpm 11 with corepack use pnpm@latest-11 (updates packageManager)
  • Optional: run pnpx codemod run pnpm-v10-to-v11
  • Move package.json#pnpm settings into pnpm-workspace.yaml; map onlyBuiltDependencies to allowBuilds
  • Keep .npmrc for auth/registry only; move other settings to YAML
  • On ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION: inspect lockfile, then pnpm clean --lockfile && pnpm install (use pnpm pm clean if clean is shadowed)
  • Approve needed postinstall builds via allowBuilds or pnpm approve-builds (e.g. prisma, @prisma/engines, esbuild)
  • Verify: pnpm install exits 0 with no package.json#pnpm warning

Migration checklist

Kiểm mục

Steps to migrate a project from pnpm 10 to pnpm 11 safely.

  • Require Node.js ≥ 22 before upgrading pnpm
  • Pin pnpm 11 with corepack use pnpm@latest-11 (updates packageManager)
  • Optional: run pnpx codemod run pnpm-v10-to-v11
  • Move package.json#pnpm settings into pnpm-workspace.yaml; map onlyBuiltDependencies to allowBuilds
  • Keep .npmrc for auth/registry only; move other settings to YAML
  • On ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION: inspect lockfile, then pnpm clean --lockfile && pnpm install (use pnpm pm clean if clean is shadowed)
  • Approve needed postinstall builds via allowBuilds or pnpm approve-builds (e.g. prisma, @prisma/engines, esbuild)
  • Verify: pnpm install exits 0 with no package.json#pnpm warning

What changed in v11

Văn bản

pnpm 11 no longer reads the pnpm field in package.json. Non-auth settings live in pnpm-workspace.yaml (or the global config.yaml). .npmrc is limited to auth and registry settings.

Build script allowlists were consolidated: onlyBuiltDependencies, neverBuiltDependencies, ignoredBuiltDependencies, onlyBuiltDependenciesFile, and ignoreDepScripts are removed. Use allowBuilds — a map of package matchers to true (allow) or false (deny). Packages not listed are treated as unreviewed; with strictDepBuilds defaulting to true, install fails until they are approved.

v11 also enables a default minimumReleaseAge window (~24 hours). Lockfile entries for packages published inside that window fail supply-chain verification (ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION). After inspecting that the lockfile change is expected, rebuild with pnpm clean --lockfile then pnpm install. During install, pnpm may auto-append versioned entries under minimumReleaseAgeExclude for packages that still need an explicit age-gate bypass — prefer that over disabling the gate wholesale unless the team chooses minimumReleaseAge: 0.

If package.json defines a script named clean, pnpm clean runs the script instead of the built-in. Force the built-in with pnpm pm clean --lockfile.

Official guides: https://pnpm.io/migration and https://pnpm.io/settings

pnpm-workspace.yaml

pnpm-workspace.yamlCấu hình
allowBuilds:
  esbuild: true
  lightningcss: true
  prisma: true
  '@prisma/engines': true

package.json#pnpm field ignored

Sự cố

After upgrading to pnpm 11, install warns that the package.json pnpm field is no longer read and lists ignored keys such as onlyBuiltDependencies.

Nguyên nhân
  • pnpm 11 stopped reading configuration from package.json#pnpm.
  • Legacy onlyBuiltDependencies / neverBuiltDependencies / ignoredBuiltDependencies were removed in favor of allowBuilds.
Cách sửa
  • Create or update pnpm-workspace.yaml at the project root.
  • Map former onlyBuiltDependencies entries to allowBuilds with value true (and neverBuilt / ignored entries to false).
  • Delete the pnpm object from package.json.
  • Optional: pnpx codemod run pnpm-v10-to-v11 to move settings automatically.
Xác minh
  • pnpm install completes without the package.json#pnpm warning
  • pnpm-workspace.yaml contains allowBuilds for required native/postinstall packages

Lockfile fails minimumReleaseAge check

Sự cố

pnpm 11 rejects lockfile entries for packages published inside the minimumReleaseAge cutoff; install suggests cleaning the lockfile and reinstalling.

Nguyên nhân
  • pnpm 11 defaults to a minimumReleaseAge window (about 24 hours) for supply-chain hardening.
  • A freshly updated lockfile (or one committed after a recent bump) includes packages younger than the cutoff.
Cách sửa
  • Inspect recent pnpm-lock.yaml changes and confirm the package bumps are intentional.
  • If expected: run pnpm clean --lockfile (or pnpm pm clean --lockfile when a package.json script named clean shadows the built-in), then pnpm install.
  • For specific trusted pins still inside the window, add them under minimumReleaseAgeExclude in pnpm-workspace.yaml (pnpm may auto-add placeholders during install).
  • Only lower or zero minimumReleaseAge if the team explicitly accepts the weaker age gate.
Xác minh
  • pnpm install exits 0
  • No ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION in output

Ignored dependency build scripts

Sự cố

Install fails or warns because dependency lifecycle scripts were not approved under allowBuilds.

Nguyên nhân
  • strictDepBuilds defaults to true in modern pnpm; unreviewed build scripts are blocked.
  • allowBuilds does not yet list packages that need postinstall/preinstall (common after migrating off onlyBuiltDependencies).
Cách sửa
  • Add each required package to allowBuilds in pnpm-workspace.yaml with true (or false to explicitly deny).
  • Or run pnpm approve-builds and set placeholders to true/false.
  • Re-run pnpm install so approved scripts execute.
Xác minh
  • pnpm install exits 0
  • Required binaries/engines are present (e.g. prisma engines postinstall ran)

Thứ tự đọc · 6