pnpm import or direct lockfile replacement for zero-downtime CI migration?

Direct answers

1. Peer dependency preservation: pnpm import does not guarantee identical peer dependency entries. pnpm v8+ improves fidelity but may normalize or deduplicate peer ranges differently than npm. Fields like peerDependenciesMeta.optional can be altered, changing installation strictness.
2. Immediate switch safety on pnpm v8+: For pure-JavaScript dependencies, switching CI directly to pnpm install --frozen-lockfile after import is generally safe. Native addons built via node-gyp must be validated on a staging branch first because pnpm's store layout and hoisting rules differ from npm's node-gyp build directory structure.
3. Store warming sequencing: Yes, the content-addressable store must be populated before enabling --offline or --frozen-lockfile in the same pipeline. A cold store forces network requests, breaking zero-downtime guarantees.

Recommended zero-downtime sequence (pnpm v8+)

1. Create a side branch. Run pnpm import to generate pnpm-lock.yaml from package-lock.json without touching node_modules.
2. Commit both lockfiles (package-lock.json and pnpm-lock.yaml) to the side branch.
3. On a staging CI agent, run pnpm install --frozen-lockfile (without --offline) to warm the store. Use a dedicated PNPM_STORE_PATH to isolate from production.
4. Verify native addons and optional dependencies on the exact CI OS/arch. Compare pnpm ls --depth=0 --prod with npm ls --depth=0 --prod to spot missing or extra peers.
5. Once staging passes, switch the main CI pipeline to pnpm install --frozen-lockfile --offline. Keep npm available in the CI image until the first production run succeeds.

Verification commands (run locally first)

# 1. Dry-run offline install to confirm store completeness
pnpm import && pnpm install --frozen-lockfile --offline --dry-run
# Exit code 0 + no network requests in logs = store is warm

# 2. Compare production dependency trees
npm ls --depth=0 --prod > npm-prod.txt
pnpm ls --depth=0 --prod > pnpm-prod.txt
diff -u npm-prod.txt pnpm-prod.txt

# 3. Inspect lockfile for resolution differences
grep -n '"resolution"' pnpm-lock.yaml
# Entries here indicate peer dependency normalization vs package-lock.json

One missing diagnostic detail

Does the project have native addons (node-gyp) or optionalDependencies with platform-specific binaries? If yes, keep npm in the CI image and run the full staging validation (step 4) before cutting over. If no, the cutover can proceed after step 3 with high confidence.

Assumptions and uncertainty

• Assumes pnpm v8.15+ (current LTS) with lockfile v6 format.
• Assumes a small, single-package (non-monorepo) Node.js application.
• Peer dependency normalization behavior may still vary for edge cases like peerDependenciesMeta.*.optional; mark for review if strict peer validation is required.
• Offline installation requires every tarball referenced in pnpm-lock.yaml to exist in the store; a single missing tarball fails the build.