Question
pnpm & CI/CD Pipelines: Does lockfile consistency influence deployment reproducibility?
Rey Dey
0 reputation · 31 Jan 2025, 10:06 UTC
113.6K views1
Loading…
0 reputation · 31 Jan 2025, 10:06 UTC
When a deployment fails after passing all local tests, the first step is to inspect the CI logs for clues that point to pnpm’s lockfile or hoisting behavior. The goal is to determine whether a mismatch between the lockfile and the resolved dependency tree, or a silent link‑creation failure, is the root cause.
pnpm’s content‑addressable store and use of hard links (or Windows junctions) can silently drop modules on agents that lack proper link support or have aggressive antivirus policies. Additionally, selective hoisting moves some dependencies to the root of node_modules, which may not be declared in package.json> and can cause missing‑module errors that only surface in the deployment environment.
Because the pnpm install --frozen-lockfile command aborts on any mismatch, the error output often references a generic lockfile inconsistency without pinpointing the offending package. This ambiguity, combined with OS‑specific link behavior, makes log‑based diagnosis challenging.
What log entries best indicate a missing module caused by pnpm’s hoisting? How can we detect silent link failures on CI agents that have restrictive antivirus or filesystem settings? Does using --frozen-lockfile guarantee reproducibility across Windows and Linux agents, or are there hidden pitfalls that still need to be addressed?
35275 reputation · 31 Jan 2025, 12:18 UTC
Yes — lockfile consistency is the single biggest factor in whether a pnpm-based deployment reproduces your local build, but it is not sufficient on its own. pnpm-lock.yaml pins the exact resolved versions and integrity hashes of every package in the graph, so a consistent lockfile gives you an identical dependency tree. It does not, by itself, guarantee identical runtime behavior across Windows and Linux agents, and it does not protect against pnpm's link-creation or hoisting quirks.
Confirmed behavior: pnpm install --frozen-lockfile fails the install if package.json and the lockfile are out of sync, and in CI environments pnpm applies frozen behavior by default. This prevents silent drift where a semver range like ^1.2.3 resolves to a newer version on the deploy agent than it did locally.
Likely explanation for your symptom class: when a deployment fails after green local tests, the usual culprits, in rough order, are (1) the lockfile not being committed or being stale, (2) a hand-edited lockfile after a merge conflict that corrupted the graph, (3) undeclared dependencies that only resolve locally because pnpm's hoisting happened to expose them, and (4) link-creation failures on agents with restrictive antivirus or filesystems without hard-link support.
pnpm isolates dependencies: only packages declared in package.json appear at the top of node_modules; everything else lives under node_modules/.pnpm. The signature of a hoisting-related failure is a MODULE_NOT_FOUND or Cannot find module 'x' error at runtime or build time for a package that is not in your package.json — it worked locally because a tool or plugin resolved it transitively, or because your local node_modules predates a clean install. Grep CI logs for the module name and check whether it appears in pnpm ls <name> output as a transitive-only dependency. The fix is to declare it explicitly, not to loosen hoisting settings.
pnpm's store relies on hard links (or junctions on Windows). Agents with aggressive antivirus scanning or filesystems without link support can produce incomplete node_modules trees without an obvious install error. Practical checks:
pnpmpnpm install --frozen-lockfile a second time — pnpm will verify and report an up-to-date or repaired tree.test -f node_modules/.bin/<your-tool>, before the build step.pnpm store path location and filesystem type, and try setting a store on the same volume as the project (cross-volume hard links fail).No. It guarantees the same resolved graph, not the same outcome. Remaining gaps:
packageManager field in package.json and Corepack.# 1. Lockfile and manifest in sync (run locally and in CI)
pnpm install --frozen-lockfile
# 2. Identical resolved trees across two clean runs of the same commit
pnpm ls --depth Infinity > tree-a.txt
# ... on second agent ...
pnpm ls --depth Infinity > tree-b.txt
diff tree-a.txt tree-b.txt
# 3. Hygiene: lockfile committed, pnpm pinned, cache keyed on lockfile
git ls-files pnpm-lock.yaml
node -p "require('./package.json').packageManager"One caveat: exact frozen-install defaults and lockfile format details vary by pnpm major version, so confirm against the version you actually run. If your failures persist after all of the above, the one detail that would change the recommendation is whether the failing module is declared in package.json — that separates a hoisting problem from a link/store problem.
Use comments to ask for clarification. Post a solution as an answer.
35,275 reputation · 31 Jan 2025, 16:06 UTC
To specifically address the "missing module" errors caused by hoisting, it is useful to distinguish between MODULE_NOT_FOUND errors occurring during the build step versus those occurring at runtime. If a module is available locally but missing in CI, it often indicates a phantom dependency—a package that is a transitive dependency of another library and was hoisted to the root node_modules by a different pnpm version or configuration.
To verify and prevent this, you can enforce a stricter hoisting policy in your .npmrc. Setting hoist=false (or using public-hoist-pattern[] to explicitly whitelist only necessary packages) forces the application to fail locally if a dependency is not explicitly declared in package.json. This shifts the detection of missing modules from the CI deployment phase to the local development phase, ensuring that --frozen-lockfile is protecting a complete and explicit dependency graph.