fix(optimizer): ensure consistent browserHash between in-memory and persisted metadata #20609

infiton · 2025-08-13T14:46:38Z

Description

This PR fixes an inconsistency in how browserHash values are set in depsOptimizer.metadata during the initial dependency scan, which can cause duplicate module instances to be loaded in the browser when the Vite dev server restarts mid–asset waterfall.

Background

At Gadget, we use Vite both for development (serving a React frontend) and for production builds. In development, each user works in an ephemeral environment (“sandbox”), which runs both:

A Vite dev server serving the frontend.
A Fastify backend server (also hosting the Vite dev server).

For frontend-only changes, the Vite server stays running and uses HMR to push updates to the browser.
For backend changes, however, we restart the entire Fastify process — which also restarts the Vite dev server.

These backend restarts are cheap and frequent, so developers often trigger them while the frontend is still loading in the browser.

The Problem

When a restart happens during the initial page load, we can hit the following sequence:

Cold boot: a new sandbox starts, and Vite builds dependency metadata (depsOptimizer._metadata.json) from scratch.
The first app request is served using this fresh metadata, and the browser begins fetching the asset waterfall (JS chunks, CSS, etc.).
Mid-load restart: the sandbox restarts while the browser is still fetching assets.
A new Vite server starts and loads the existing _metadata.json from disk (written in step 1).
Remaining asset requests in the waterfall are served from this second server.

Because browserHash in the in-memory metadata for the first server was not the same value eventually persisted to _metadata.json, the same dependency can be served with two different browser hashes across the restart.

If the dependency is React (or any library that maintains singleton state), this results in the browser having duplicate copies of the module, causing broken HMR, hydration errors, and subtle runtime issues.

Solution

This patch ensures that before resolving scanProcessing in the optimizer, we eagerly set the browserHash on the in-memory metadata to the value that will later be written to disk.

By doing this, both:

The first server (before writing to disk)
Any subsequent server (loading from _metadata.json)

will use identical browser hashes for the same dependency, as long as we wait for the initial scan to complete before resolving dependencies.

Why This Matters

Fixes a correctness issue that can manifest in real-world setups where Vite dev servers restart mid-load.
Ensures consistency between the in-memory and persisted metadata for dependencies.
Prevents hard-to-debug runtime errors caused by multiple versions of a singleton dependency being loaded into the same page.

…nd persisted metadata When the dev server restarts mid–asset waterfall and loads cached `_metadata.json`, inconsistent `browserHash` values can cause duplicate instances of the same dependency to be loaded (e.g. multiple React copies). This patch sets the `browserHash` eagerly in memory before resolving `scanProcessing`, ensuring both the in-memory metadata and the persisted metadata use the same value.

infiton · 2025-08-18T13:59:03Z

cc @bluwy is there anything I need to do to get this into triage?

sapphi-red · 2025-08-21T12:07:19Z

Hmm, I think Vite expects all assets used in the same page to be loaded from the same Vite server instance (i.e. Vite server is not restarted during loading a page and the assets).

Mid-load restart: the sandbox restarts while the browser is still fetching assets.

A new Vite server starts and loads the existing _metadata.json from disk (written in step 1).

Remaining asset requests in the waterfall are served from this second server.

Wouldn't this cause the WebSocket connection to disconnect and the client to call location.reload()?

infiton · 2025-08-21T15:30:25Z

Vite expects all assets used in the same page to be loaded from the same Vite server instance

it makes sense that this would be an expectation, and I think there's a unique setup in Gadget that is exposing this issue where others probably haven't seen this ever

Wouldn't this cause the WebSocket connection to disconnect and the client to call location.reload()?

not necessarily; we see this happen the most frequently in react router SSR mode where the initial document is served and it loads some big modules like react and eventually it's hmr runtime which then loads the vite client (which then attempts to set up an hmr connection); if the server restarts while the hmr socket is trying to connect it can reject with:

Uncaught (in promise) Error: WebSocket closed without opened.
    at WebSocket.<anonymous> (client:454:22)

in ordinary situations the vite client will start polling for a reconnect, however in the meantime a duplicate copy of react loads and the page load crashes with

chunk-HUR6ZVB7.js?v=c5431c96:9255 TypeError: Cannot read properties of null (reading 'useContext')
    at Object.useContext (chunk-4S2OYCSJ.js?v=d029a2ac:1062:29)
    at useParams (chunk-HUR6ZVB7.js?v=d029a2ac:5464:28)
    at useErrorBoundaryProps (chunk-HUR6ZVB7.js?v=d029a2ac:6547:13)
    at WithErrorBoundaryProps2 (chunk-HUR6ZVB7.js?v=d029a2ac:6561:19)
    at renderWithHooks (chunk-ZSAHMUTT.js?v=c5431c96:11596:26)
    at mountIndeterminateComponent (chunk-ZSAHMUTT.js?v=c5431c96:14974:21)
    at beginWork (chunk-ZSAHMUTT.js?v=c5431c96:15962:22)
    at beginWork$1 (chunk-ZSAHMUTT.js?v=c5431c96:19806:22)
    at performUnitOfWork (chunk-ZSAHMUTT.js?v=c5431c96:19251:20)
    at workLoopSync (chunk-ZSAHMUTT.js?v=c5431c96:19190:13)

In general do you agree that when vite first builds the optimized deps that the browser hash before and after restart should be consistent? It feels wrong that the browser hash in memory after the optimizer is finished doesn't match what it just wrote to disk

sapphi-red · 2025-08-22T04:58:12Z

In general do you agree that when vite first builds the optimized deps that the browser hash before and after restart should be consistent? It feels wrong that the browser hash in memory after the optimizer is finished doesn't match what it just wrote to disk

I think it is better to be like that, but not necessarily have to be. So I'm not opposed unless it breaks other behaviors.

Wouldn't this cause the WebSocket connection to disconnect and the client to call location.reload()?

not necessarily; we see this happen the most frequently in react router SSR mode where the initial document is served and it loads some big modules like react and eventually it's hmr runtime which then loads the vite client

Hmm, that could happen. That said, unless there's a reason, I'll recommend loading the client before any other scripts so that the file changes during the initial load is sent to the browser properly.

sapphi-red · 2025-08-22T05:01:51Z

packages/vite/src/node/optimizer/optimizer.ts

+              for (const dep of Object.keys(metadata.discovered)) {
+                metadata.discovered[dep].browserHash = metadata.browserHash
+              }


It looks like this would override metadata.discovered[dep].browserHash that is set in addMissingDep call above.

vite/packages/vite/src/node/optimizer/optimizer.ts

Lines 599 to 607 in e899bc7

// Adding a browserHash to this missing dependency that is unique to

// the current state of known + missing deps. If its optimizeDeps run

// doesn't alter the bundled files of previous known dependencies,

// we don't need a full reload and this browserHash will be kept

browserHash: getDiscoveredBrowserHash(

metadata.hash,

depsFromOptimizedDepInfo(metadata.optimized),

depsFromOptimizedDepInfo(metadata.discovered),

),

I guess this would break the behavior written in the comment.

taking a look; if there is behaviour that breaks I'll write a test to catch it

re-reading the code I think since this is the first deps build when !cachedMetadata this override should be ok; at this point all the deps found during the initial scan processing are known and we can assign a stable hash (I think this is strongly signalled by the fact that this is the data that we will write down to disk)

it doesn't look like there is a test to cover the behaviour that was being addressed in #7378 and it sounds like setting one up would be tricky

@patak-dev any thoughts on this?

I read the code several times and I think you're right; this assignment is fine.

But while thinking about that, I noticed that the fundamental problem we have is that the browserHash for the discovered deps can be different from metadata.browserHash which will be stored to the metadata file.
addMissingDep generates browserHash using getDiscoveredBrowserHash and that hash will be used through out the same process for that dep. But that per-dep browserHash won't be saved to the metadata, only the top-level browserHash is saved.
I think this means the browserHash for any dep that was added by addMissingDep would have a different hash when restarting the server. The other places addMissingDep is called are:

vite/packages/vite/src/node/optimizer/optimizer.ts

Line 574 in 79d10ed

missing = addMissingDep(id, resolved)

vite/packages/vite/src/node/optimizer/optimizer.ts

Line 692 in 79d10ed

addMissingDep(dep, result.metadata.optimized[dep].src!)

I think these also have to be fixed for the problem you have. That said, I'm not sure how we can fix the other places.

I'm fine with leaving the others for now if you prefer that.

yah I don't see a great fix for that; but I will think about it more

if possible it'd be great to get this fix in and then I can see if I can find a solution for the others

infiton · 2025-08-22T12:53:12Z

That said, unless there's a reason, I'll recommend loading the client before any other scripts so that the file changes during the initial load is sent to the browser properly.

yah that makes sense, unfortunately in our case we don't control the load order as it is determined by (1) the frontend framework (react-router v7 in this case) and then (2) our users that can write arbitrary code and our goal is to make the underlying tech as reliable as possible

infiton · 2025-08-22T13:36:12Z

I'm going on vacation for a week, so tagging in my colleague @airhorns to address any comments while I'm away

airhorns · 2025-08-26T17:46:11Z

Just following up here -- happy to make any changes necessary or address comments

Hmm, that could happen. That said, unless there's a reason, I'll recommend loading the client before any other scripts so that the file changes during the initial load is sent to the browser properly.

For this, you are right, but I think even if the vite client is the first script loaded on the page, we still can't guarantee that the vite server didn't reboot in between when the page was served and then the client is requested. I think in normal local operation it'd be incredibly unlucky, but in remote development contexts like Github codespaces / codesandbox / Gadget etc, I think the window of opportunity gets bigger.

I am not incredibly familiar with Vite's internals, but AFAICT this shouldn't have much of a negative performance impact, and corrects the bug for these users, so is there a downside to including this fix?

infiton · 2025-09-03T17:10:04Z

back from vacation now so I can respond to any feedback

infiton · 2025-09-08T13:24:58Z

ping @sapphi-red think we are ok to merge this?

sapphi-red · 2025-09-13T16:01:07Z

I'd like another member to take a look.

bluwy

I'm not very familiar with the optimizer flow, but this seem fine to me.

For the new await depsOptimizer.scanProcessing additions, can we add a comment about explaining why we're waiting for processing? I think it's to await for a stable browserHash as it could change?

infiton · 2025-09-17T21:31:17Z

@sapphi-red you feel comfortable to merge?

bluwy · 2025-09-17T23:53:43Z

My comment hasn't been addressed yet. And I'm sure sapphi will merge as soon as he feels ready, there's no need to push as the PR isn't stale yet.

hi-ogawa · 2025-09-18T00:54:28Z

/ecosystem-ci run

pkg-pr-new · 2025-09-18T00:55:18Z

Open in StackBlitz

npm i https://pkg.pr.new/vite@20609

commit: 95807da

vite-ecosystem-ci · 2025-09-18T02:57:00Z

📝 Ran ecosystem CI on 80d8a72: Open

suite	result	latest scheduled
laravel	❌ failure	❌ failure
unocss	❌ failure	❌ failure
sveltekit	❌ failure	✅ success

✅ astro, analogjs, nuxt, marko, histoire, one, ladle, react-router, rakkas, vite-environment-examples, qwik, storybook, vite-plugin-pwa, quasar, vike, vite-plugin-svelte, vite-plugin-vue, vite-plugin-react, waku, vitepress, vite-plugin-rsc, vuepress, vite-setup-catalogue, vitest, vite-plugin-cloudflare

sapphi-red · 2025-09-18T03:10:10Z

~~Hmm, it seems this change breaks sveltekit's test. That has to be checked before merging as well.~~
sveltekit failed with main branch as well, so the failure is not related to this PR.
https://github.com/vitejs/vite-ecosystem-ci/actions/runs/17817427184/job/50653363205

hi-ogawa

I'm also not sure this will the complete fix for the explained use case, but this change looks okay on its own and as a start.

By searching ?v= injection, I also saw this line for example. Is this code path not relevant or should also await scanProcessing or is it already guaranteed somehow?

vite/packages/vite/src/node/plugins/resolve.ts

Lines 836 to 838 in d8169f0

    
           const versionHash = depsOptimizer.metadata.browserHash 
        
           if (versionHash && isJsType) { 
        
             resolved = injectQuery(resolved, `v=${versionHash}`)

infiton · 2025-09-23T12:52:11Z

hey folks, is there any thing I can do to help get this released?

hi-ogawa · 2025-09-24T00:42:57Z

Btw, have you tested this patch on your platform? or does it require this to be published on npm? FYI, as a preview release, the package made from this PR can be installed like #20609 (comment)

infiton · 2025-09-24T04:39:17Z

Btw, have you tested this patch on your platform? or does it require this to be published on npm? FYI, as a preview release, the package made from this PR can be installed like #20609 (comment)

yah we've been running with this patch on top of version of 6.3.5 for over a month now and it's completely resolved our issue

sapphi-red

I think these two needs to be addressed.

For the new await depsOptimizer.scanProcessing additions, can we add a comment about explaining why we're waiting for processing? I think it's to await for a stable browserHash as it could change?
#20609 (review)

By searching ?v= injection, I also saw this line for example. Is this code path not relevant or should also await scanProcessing or is it already guaranteed somehow?

vite/packages/vite/src/node/plugins/resolve.ts

Lines 836 to 838 in d8169f0

const versionHash = depsOptimizer.metadata.browserHash

if (versionHash && isJsType) {

resolved = injectQuery(resolved, `v=${versionHash}`)

#20609 (review)

This comment was marked as duplicate.

Sign in to view

sapphi-red added the feat: deps optimizer Esbuild Dependencies Optimization label Aug 21, 2025

This comment was marked as duplicate.

Sign in to view

sapphi-red reviewed Aug 22, 2025

View reviewed changes

sapphi-red added the p2-edge-case Bug, but has workaround or limited in scope (priority) label Sep 1, 2025

sapphi-red added 2 commits September 14, 2025 00:48

perf: only wait if needed

b8dd327

chore: add comment

80d8a72

sapphi-red approved these changes Sep 13, 2025

View reviewed changes

sapphi-red changed the title ~~fix(optimize-deps): ensure consistent browserHash between in-memory a…~~ fix(optimizer): ensure consistent browserHash between in-memory and persisted metadata Sep 13, 2025

sapphi-red requested review from patak-dev and bluwy September 13, 2025 15:57

bluwy reviewed Sep 17, 2025

View reviewed changes

vite-ecosystem-ci bot added the trigger: preview label Sep 18, 2025

This comment was marked as duplicate.

Sign in to view

hi-ogawa approved these changes Sep 18, 2025

View reviewed changes

Merge branch 'main' into optimize-deps-browser-hash

95807da

sapphi-red requested changes Oct 1, 2025

View reviewed changes

	// Adding a browserHash to this missing dependency that is unique to
	// the current state of known + missing deps. If its optimizeDeps run
	// doesn't alter the bundled files of previous known dependencies,
	// we don't need a full reload and this browserHash will be kept
	browserHash: getDiscoveredBrowserHash(
	metadata.hash,
	depsFromOptimizedDepInfo(metadata.optimized),
	depsFromOptimizedDepInfo(metadata.discovered),
	),

	const versionHash = depsOptimizer.metadata.browserHash
	if (versionHash && isJsType) {
	resolved = injectQuery(resolved, `v=${versionHash}`)

Uh oh!

fix(optimizer): ensure consistent browserHash between in-memory and persisted metadata #20609

Are you sure you want to change the base?

fix(optimizer): ensure consistent browserHash between in-memory and persisted metadata #20609

Conversation

infiton commented Aug 13, 2025

Description

Background

The Problem

Solution

Why This Matters

Uh oh!

infiton commented Aug 18, 2025

Uh oh!

This comment was marked as duplicate.

This comment was marked as duplicate.

This comment was marked as duplicate.

sapphi-red commented Aug 21, 2025

Uh oh!

infiton commented Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as duplicate.

sapphi-red commented Aug 22, 2025

Uh oh!

sapphi-red Aug 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

infiton Aug 22, 2025

Choose a reason for hiding this comment

Uh oh!

infiton Aug 22, 2025

Choose a reason for hiding this comment

Uh oh!

sapphi-red Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

infiton Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

infiton commented Aug 22, 2025

Uh oh!

infiton commented Aug 22, 2025

Uh oh!

airhorns commented Aug 26, 2025

Uh oh!

infiton commented Sep 3, 2025

Uh oh!

infiton commented Sep 8, 2025

Uh oh!

sapphi-red commented Sep 13, 2025

Uh oh!

bluwy left a comment

Choose a reason for hiding this comment

Uh oh!

infiton commented Sep 17, 2025

Uh oh!

bluwy commented Sep 17, 2025

Uh oh!

hi-ogawa commented Sep 18, 2025

Uh oh!

pkg-pr-new bot commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as duplicate.

vite-ecosystem-ci bot commented Sep 18, 2025

Uh oh!

sapphi-red commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hi-ogawa left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

infiton commented Sep 23, 2025

Uh oh!

hi-ogawa commented Sep 24, 2025

Uh oh!

infiton commented Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

infiton commented Aug 21, 2025 •

edited

Loading

sapphi-red Aug 22, 2025 •

edited

Loading

pkg-pr-new bot commented Sep 18, 2025 •

edited

Loading

sapphi-red commented Sep 18, 2025 •

edited

Loading

hi-ogawa left a comment •

edited

Loading

infiton commented Sep 24, 2025 •

edited

Loading