Lockfile persistence after a package.json version rollback in Vite

Short answer

Hash-based invalidation should be the default: Vite should rebuild the pre-bundled dependency cache whenever the resolved set of dependency versions no longer matches what the cache was built from — including rollbacks, not just upgrades. A configuration flag should exist only as an escape hatch (optimizeDeps.force already covers the manual case); the safe behavior should not be opt-in.

Likely explanation vs. confirmed behavior

Confirmed (well-established): Vite pre-bundles dependencies with esbuild into node_modules/.vite/deps to avoid hundreds of individual module requests in the dev server. It writes metadata alongside the bundles (a hash derived from the lockfile, package.json dependency fields, and relevant config) and skips re-bundling when that hash matches. Setting optimizeDeps.force: true, running vite --force, or deleting node_modules/.vite forces a rebuild.

Likely explanation for the reported bug: the invalidation key covers the inputs Vite hashes, but if a rollback path — for example, a manual edit to package.json without a corresponding lockfile update, or a git checkout that restores an older package.json while node_modules still contains the newer install — leaves the hash unchanged relative to the cached metadata, Vite reuses the stale bundle. The browser then executes code built against the newer dependency's API while the application source targets the old one. The failure surfaces as confusing runtime errors rather than a build error, which is what makes it expensive to diagnose.

Exact hash inputs and edge cases vary across Vite versions, so treat the precise trigger as version-dependent and verify against your installed release.

Why hash-based invalidation is the right default

• Correctness over speed. The current bias toward avoiding re-bundles optimizes for startup time, but a wrong cache costs far more developer time than a redundant 1–2 second re-bundle. A cache that can silently serve the wrong dependency version violates the principle that dev output should match the declared dependency graph.
• Rollbacks are symmetric with upgrades. There is no principled reason an upgrade should invalidate and a downgrade should not. Any strategy keyed on "version increased" or file timestamps is fragile; a content hash of the resolved versions treats both directions identically.
• Git workflows amplify the problem. Branch switches and git stash cycles routinely change package.json and lockfiles without any package-manager command running. Timestamp-based heuristics miss these; content hashing catches them on the next dev-server start.

What the design should look like

1. Include the resolved version of every optimized dependency (from the lockfile, falling back to node_modules/<pkg>/package.json version fields) in the cache metadata hash.
2. On mismatch, rebuild automatically and log a single line naming the dependencies whose versions changed, so the rebuild is explainable rather than mysterious.
3. Keep optimizeDeps.force for cases the hash cannot see (e.g., patched packages via patch-package or linked local packages whose contents change without a version bump).
4. Optionally add an explicit optimizeDeps.invalidation: 'auto' | 'manual' setting for teams with monorepo setups where hashing is expensive — but default it to 'auto'.

What to do today

Until Vite ships stricter invalidation, make the workaround part of the rollback workflow rather than relying on memory:

# after rolling back a dependency version
npm install        # sync node_modules and lockfile
npx vite --force   # or: rm -rf node_modules/.vite

Teams that hit this repeatedly can add a postinstall script that clears node_modules/.vite, trading a few seconds of startup for deterministic cache state after every dependency change.

Verifying which bundle you are actually serving

To confirm the stale-cache hypothesis in a given project: start the dev server, open the browser's network tab, and inspect the response for the dependency under /node_modules/.vite/deps/ — the banner comment in the generated chunk identifies the pre-bundled package. Compare it against the version in node_modules/<pkg>/package.json. If they disagree after a rollback, the cache is stale and npx vite --force should make the runtime errors disappear; if they agree, the bug lies elsewhere and the cache is a red herring.

Open question

One diagnostic detail would sharpen the recommendation: whether the rollback was done via the package manager (lockfile updated) or by editing package.json / checking out a branch (lockfile untouched). If the lockfile changed and Vite still served the stale bundle, that is a genuine invalidation bug worth reporting with a reproduction; if the lockfile never changed, the behavior is closer to an expected consequence of an inconsistent working tree, and the fix belongs in the workflow rather than in Vite.