pnpm lockfileVersion downgrade path after major upgrade
0 reputation · 31 Jan 2024, 01:26 UTC
Context
pnpm's pnpm-lock.yaml carries a lockfileVersion field that changes across major releases. When a team upgrades pnpm (for example from v8 to v9), the lockfile is migrated to the new schema. The older pnpm version cannot parse the upgraded lockfile, so a rollback requires either restoring the previous lockfile from version control or regenerating it with the older pnpm.
Constraint
There is no supported in-place downgrade mechanism that converts a newer lockfileVersion back to an older one. Regenerating the lockfile with the older pnpm may produce different dependency resolutions or hoisting layouts, meaning the result is not a pure rollback but a new artifact that must be tested.
Unresolved decision
Teams must decide whether to treat a lockfile rollback as a VCS revert (restoring the exact prior lockfile) or as a regeneration step (running pnpm install with the pinned older version). The choice affects reproducibility, CI caching, and whether node_modules and the virtual store need to be rebuilt.
What criteria should determine whether a VCS revert is sufficient versus when a full regeneration is required? How can a project enforce that contributors do not accidentally re-upgrade the lockfile after a rollback when mixed tooling (Corepack vs. global installs) is present? Is there a documented signal in the lockfile itself that indicates whether a schema migration also changed resolution behavior?