resolution-mode trade-off: time-based reproducibility versus highest currency for repeatable CI builds

Direct answer

Commit an .npmrc that pins resolution-mode=time-based together with the peer-dependency settings, pin the pnpm major version through packageManager and corepack, and run pnpm install --frozen-lockfile in CI. time-based meaningfully reduces churn between lockfile regenerations, but it is not a freeze: when the lockfile is regenerated monthly, the recorded time reference moves forward, so legitimate in-range updates published before regeneration can still be selected. lowest-direct does not reliably pin old transitive dependencies or guarantee security coverage. A CI checklist is insufficient because local installs and lockfile regeneration can use different pnpm versions or .npmrc values.

1. time-based versus highest

Likely explanation. time-based selects the newest matching version that existed at the lockfile's recorded time reference. highest always selects the newest matching version. Between regenerations, time-based suppresses versions published after the reference, while highest can drift on every rebuild. Once the lockfile is regenerated, however, the reference advances and both modes can select the same newly published, in-range version if it predates the new reference. The practical difference is therefore intra-cycle stability, not permanent version freezing.

Confirmed facts. The default resolution-mode differs across pnpm major versions, so inheriting the default is unsafe. Changing the mode on an existing lockfile does not alter already locked entries until the lockfile is regenerated or affected dependencies change. The exact time-reference semantics and whether the reference advances on regeneration should be confirmed for your installed pnpm version.

2. lowest-direct and transitive dependency risk

lowest-direct forces only direct dependencies to their lowest satisfying versions. Transitive dependencies are still resolved by their own ranges under the active resolution mode, so there is no fixed frequency with which it pulls old transitive versions, and it cannot guarantee that security fixes are present. Audit the committed graph in CI with pnpm audit, pnpm outdated, and pnpm ls <package> or pnpm why <package> to locate vulnerable transitive instances without manual tree inspection.

3. Commit .npmrc; do not rely on a checklist

Peer-dependency settings such as auto-install-peers, dedupe-peer-dependents, and strict-peer-dependencies can add, remove, or dedupe packages without changing any semver range. Pin them in the same committed .npmrc as resolution-mode. Also pin packageManager in package.json and use corepack in CI so local and CI pnpm major versions match.

Steps for this case

1. Add to the committed .npmrc:

   resolution-mode=time-based
   auto-install-peers=true
   dedupe-peer-dependents=true
   strict-peer-dependencies=true

   Omit or adjust peer keys only if your workspace does not use them.
2. Add the pnpm major version to package.json:

   "packageManager": "pnpm@<major>"

   Replace <major> with the exact major your team standardizes on.
3. Commit pnpm-lock.yaml alongside .npmrc.
4. In CI, run pnpm install --frozen-lockfile to detect drift, then pnpm audit and pnpm outdated for security review.

Verification

• pnpm config get resolution-mode and inspect repo and CI .npmrc to confirm the effective mode and peer keys.
• Regenerate the lockfile twice with the same pnpm version and .npmrc, then compare pnpm-lock.yaml hashes.
• Confirm pnpm versions match locally and in CI with pnpm --version.

Missing diagnostic detail. What pnpm major version runs locally and in CI? If they differ, inherited defaults and lockfile format behavior can differ even with an explicit resolution-mode, which changes whether you must also standardize the pnpm version before trusting the committed lockfile.