Fix pnpm frozen lockfile error on Vercel deploy

Problem

Vercel deployment fails during the install step because the lockfile format does not match the pnpm version Vercel is using:

 ERR_PNPM_OUTDATED_LOCKFILE  Cannot install with "frozen-lockfile" because
pnpm-lock.yaml is not up to date with package.json.

Note that in CI environments this setting is true by default. If you don't
want pnpm to fail on outdated lockfile, set the `frozen-lockfile` setting to
false in .npmrc or pass the --no-frozen-lockfile flag.

This typically happens when the local pnpm version differs from the version Vercel detects, causing a lockfile format mismatch (e.g., lockfile version 9.0 generated by pnpm 9.x but Vercel runs pnpm 8.x).

Solution

Step 1: Pin the pnpm version in package.json

// package.json
{
  "name": "my-app",
  "packageManager": "pnpm@9.15.0",
  "engines": {
    "node": ">=20"
  }
}

Step 2: Regenerate the lockfile with the pinned version

corepack enable
corepack use pnpm@9.15.0
pnpm install --lockfile-only

Step 3: Commit both package.json and pnpm-lock.yaml

git add package.json pnpm-lock.yaml
git commit -m "pin pnpm version and regenerate lockfile"

Why It Works

Vercel uses Corepack to detect and install the package manager version specified in the packageManager field of package.json. Without this field, Vercel falls back to a default pnpm version that may differ from the one used locally. Different pnpm major versions produce incompatible lockfile formats (pnpm 8 uses lockfile v6, pnpm 9 uses lockfile v9). When the versions mismatch, --frozen-lockfile (enabled by default in CI) rejects the lockfile because it cannot parse it correctly. Pinning the version ensures the same pnpm runs locally and on Vercel.

Context

• The packageManager field is a Node.js standard supported by Corepack, not specific to Vercel
• Corepack ships with Node.js 16.13+ but must be enabled with corepack enable
• The same fix applies to other CI providers (GitHub Actions, GitLab CI, CircleCI) -- ensure Corepack is enabled in your CI pipeline
• Do not add shamefully-hoist=true or --no-frozen-lockfile as workarounds -- these mask the real version mismatch and can cause dependency resolution issues
• If migrating from pnpm 8 to 9, also check for breaking changes in pnpm-workspace.yaml and .npmrc settings
• Run pnpm --version locally to verify the active version matches packageManager