React loads twice in first load from cold started dev server

[uhyo]

Reproduction Steps

1. cd packages/example-fs-routing
2. Make sure that ./node_modules/.vite does not exist (delete it if exists)
3. pnpm dev (runs Vite dev server)
4. Open http://localhost:5173/

Console logs below error:

Invalid hook call. Hooks can only be called inside of the body of a function component. This could happen for one of the following reasons:
1. You might have mismatching versions of React and the renderer (such as React DOM)
2. You might be breaking the Rules of Hooks
3. You might have more than one copy of React in the same app
See https://react.dev/link/invalid-hook-call for tips about how to debug and fix this problem.

Note that then the page immediately reloads automatically. On second request this issue disappears.

To reproduce it again, you need to remove .vite and restart the Vite dev server.

Vite Log

Vite log:

4:21:07 PM [vite] (client) ✨ new dependencies optimized: @funstack/router
4:21:07 PM [vite] (client) ✨ optimized dependencies changed. reloading

Vite seems to detect the drift as 'optimized dependencies changed' and perform the reload.

Analysis

As the error message suggests, two copies of React are loaded. Chrome devtools revealed that there does exist two different request chains that load different copies of React.

1st copy:

Request initiator chain
http://localhost:5173/
http://localhost:5173/@id/_x00_virtual:vite-rsc/entry-browser
http://localhost:5173/@fs/home/uhyo/repos/funstack-static/packages/static/dist/entries/client.mjs
http://localhost:5173/@fs/home/uhyo/repos/funstack-static/packages/static/dist/client/entry.mjs
http://localhost:5173/node_modules/.vite/deps/react.js?v=edd0de91
http://localhost:5173/node_modules/.vite/deps/rolldown-runtime-BvCyGRYZ.js?v=a27e72b2

2nd copy:

Request initiator chain
http://localhost:5173/
http://localhost:5173/@id/_x00_virtual:vite-rsc/entry-browser
http://localhost:5173/@fs/home/uhyo/repos/funstack-static/packages/static/dist/entries/client.mjs
http://localhost:5173/@fs/home/uhyo/repos/funstack-static/packages/static/dist/client/entry.mjs
http://localhost:5173/@fs/home/uhyo/repos/funstack-static/node_modules/.pnpm/@vitejs+plugin-rsc@0.5.27_react-dom@19.2.7(...snip...)@vitejs/plugin-rsc/dist/browser.js?v=a27e72b2
http://localhost:5173/@id/_x00_virtual:vite-rsc/client-package-proxy/@funstack/router
http://localhost:5173/node_modules/.vite/deps/@funstack_router.js?v=6768cc48
http://localhost:5173/node_modules/.vite/deps/@funstack_static_n_react.js?v=4a349293

The 2nd copy appears as @funstack_static_n_react.js.

On the 2nd request (after deps has been optimized), http://localhost:5173/node_modules/.vite/deps/react.js is no longer a whole React module, but a re-export of @funstack_static_n_react.js:

Request initiator chain
http://localhost:5173/@vite/client
http://localhost:5173/
http://localhost:5173/@id/_x00_virtual:vite-rsc/entry-browser
http://localhost:5173/@fs/home/uhyo/repos/funstack-static/packages/static/dist/entries/client.mjs
http://localhost:5173/@fs/home/uhyo/repos/funstack-static/packages/static/dist/client/entry.mjs
http://localhost:5173/node_modules/.vite/deps/react.js?v=4a349293
http://localhost:5173/node_modules/.vite/deps/@funstack_static_n_react.js?v=4a349293

[uhyo]

Root-cause investigation

I dug into why this happens (beyond the #129 fix). Short version: the necessary condition is on the FUNSTACK side, but the actual breakage is an unstable "canonical React chunk" in Vite's dependency optimizer that flips between optimization passes. Verified end-to-end with a Playwright + .vite/deps/_metadata.json harness on a cold dev server.

Environment: vite@8.1.0 (rolldownVersion 1.1.2), @vitejs/plugin-rsc@0.5.27, React 19.2.

The necessary condition (FUNSTACK side)

In configEnvironment we push both of these to the client optimizeDeps.include:

config.optimizeDeps.include.push(
  "@funstack/static > react",
  "@funstack/static > react-dom",
);

Because react is a peerDependency of @funstack/static, @funstack/static > react resolves to the same physical file as the bare react the optimizer scanner already discovers (via the client entry / react-error-boundary). I confirmed this in the optimizer metadata — both entries report src: node_modules/react/index.js.

So the client optimizer ends up with two optimized chunks of identical React source:

• react.js
• @funstack_static_n_react.js

The mechanism: the canonical chunk flips on re-optimization

Within a single optimizer pass these two are deduplicated — one chunk holds the real bundled React (CommonJS-wrapped), the other just re-exports it. But which one is canonical is not stable across passes. Captured live:

	Pass 1 (cold start)	Pass 2 (after @funstack/router discovered)
react.js	CANONICAL (real React)	ALIAS → @funstack_static_n_react.js
@funstack_static_n_react.js	ALIAS → react.js	CANONICAL (real React)
browserHash	…430cabdb	…79ec8348

Now overlay @vitejs/plugin-rsc's late discovery of client packages:

1. The browser entry loads eagerly in pass 1 → its import "react" binds to react.js?v=430cabdb (real React instance A).
2. The RSC payload references @funstack/router's "use client" component → the browser requests virtual:vite-rsc/client-package-proxy/@funstack/router. This is the first time the client optimizer sees @funstack/router, so it triggers a re-optimization (pass 2).
3. Pass 2 flips the canonical to @funstack_static_n_react.js. @funstack/router's internal import "react" resolves to @funstack_static_n_react.js?v=79ec8348 (real React instance B).
4. Both real instances are now live in the same document → Invalid hook call → Cannot read properties of null (reading 'useMemo') in <Router>. The flip changed react.js's content (real → alias) → its hash changed → Vite forces the reload. After reload everything is pass-2-consistent → the bug "self-heals," exactly as reported.

The browser network trace from my repro shows both top-level React files loaded in the same first render:

/node_modules/.vite/deps/react.js?v=430cabdb                  ← instance A (client entry)
/@id/__x00__virtual:vite-rsc/client-package-proxy/@funstack/router
/node_modules/.vite/deps/@funstack_static_n_react.js?v=79ec8348  ← instance B (router)
=> distinct top-level react files loaded: react.js + @funstack_static_n_react.js

Why a plain @vitejs/plugin-rsc setup does NOT reproduce

I built a minimal @vitejs/plugin-rsc project (no FUNSTACK) that renders @funstack/router from a server component — same plugin-rsc, same late discovery. It has only one React chunk, so adding @funstack/router leaves react.js byte-identical → no flip:

[pre]  react.js: CANONICAL    @funstack_static_n_react.js: (absent)
[post] react.js: CANONICAL    @funstack_static_n_react.js: (absent)   ← no flip
Vite log: "✨ new dependencies optimized: @funstack/router"   ← note: NO "reloading"
console errors: (none)

This isolates the duplicate same-source React entry as the necessary condition.

Why we can't just drop the nested entries

I tested swapping @funstack/static > react → bare react. It does kill the duplicate and the flip — but it breaks CommonJS interop:

SyntaxError: The requested module '/node_modules/.vite/deps/react_jsx-runtime.js' does not provide an export named 't'

The nested entries pin React's CJS-wrapper form so it stays consistent with the also-nested @funstack/static > @vitejs/plugin-rsc/... chunk (we have to exclude @funstack/static itself from optimizeDeps, since its prebuilt dist imports plugin-rsc + React as CommonJS). So the nested entries are load-bearing, not gratuitous — they just have this duplicate-chunk side effect.

Why #129 is the right fix

#129 keeps the nested entries (interop intact) and instead pre-bundles the client packages so @funstack/router lands in pass 1, eliminating the re-optimization that triggers the flip. Verified by pre-bundling @funstack/router in the client env:

[pre]  react.js: CANONICAL    @funstack_static_n_react.js: ALIAS ->react.js
[post] react.js: CANONICAL    @funstack_static_n_react.js: ALIAS ->react.js   ← no flip
browserHash: 9a84f5d8 -> 9a84f5d8 (unchanged)   errors: none

Two React chunks still exist, but with no second pass the canonical never flips → single live instance.

Summary

It's a three-way interaction:

• FUNSTACK registers two optimized chunks of identical React (necessary condition).
• @vitejs/plugin-rsc defers client-package discovery to request time, forcing a re-optimization (the trigger — present in a plain plugin-rsc setup too, harmless without the duplicate).
• Vite/rolldown re-derives the canonical of two same-source entries and picks the opposite one when the entry set grows (the fragility that turns the duplicate into two live instances).

#129 addresses the trigger. There's also a deeper structural fix available on our side — represent React as a single optimized chunk while preserving the nested-plugin-rsc interop — which I'll prototype next so the failure mode becomes impossible rather than merely avoided. I'm also filing the Vite-level half (unstable canonical across re-optimization) upstream; draft in the next comment.

[uhyo]

---

Draft: upstream Vite issue (updated)

Reframed after trying to build a standalone repro for the react/jsx-runtime 't' interop break: it turns out to be the same root cause as the duplicate-React flip — the same cross-pass instability of a duplicated optimized chunk — just a sharper, link-time surface that only appears in richer (real-framework) graphs. So this is now one bug with a clean minimal repro (the duplicate-React flip) plus the 't' documented as another face of it, rather than two separate symptoms.

The minimal repro is pushed: https://github.com/uhyo/vite-rsc-deps-issue-repro/tree/repro/duplicate-react-cold-start

---

Dep optimizer: re-optimization can flip which duplicated chunk is "canonical" for a module, breaking module singletons (duplicate React on a cold-started dev server)

Summary

When two optimizeDeps.include entries resolve to the same module (e.g. react and x > react, where x peer-depends on react), the optimizer emits two chunks for it — one holds the real (CJS-wrapped) module, the other re-exports it. Which one is "canonical" vs. the re-export is not stable across optimizer passes: a re-optimization can swap them.

If that re-optimization is triggered after some modules have already been served (a dependency discovered at request time), a consumer loaded before the swap and one loaded after end up bound to two different real instances of the module. For React this is Invalid hook call / Cannot read properties of null (reading 'useState'); the page then auto-reloads (optimized dependencies changed. reloading) and the error vanishes — so it's cold-start-only, first-render-only.

A minimal, framework-free repro is below. The same instability has a sharper, link-time surface in richer (real-framework) graphs — a react/jsx-runtime does not provide an export named 't' error — described at the end as another face of the same bug.

The trigger path (via @vitejs/plugin-rsc): a "use client" package imported by a server component is reached on the browser through a request-time virtual:vite-rsc/client-package-proxy/<pkg> module that the optimizer's initial scan can't follow — so the package (and the React it imports) is discovered on the first render and forces the re-optimization.

Environment

• vite@8.1.0 (rolldown bundler, rolldownVersion 1.1.2)
• @vitejs/plugin-rsc@0.5.27
• React 19.2

---

Repro (minimal, no framework)

https://github.com/uhyo/vite-rsc-deps-issue-repro/tree/repro/duplicate-react-cold-start — depends only on react, react-dom, vite, @vitejs/plugin-rsc, and a trivial local client-widget package (a "use client" component that calls a hook).

pnpm install && rm -rf node_modules/.vite && pnpm dev
# open the URL; first load throws Invalid hook call, then auto-reloads

The only non-default config is the trigger — a second React entry in the client optimizer:

// vite.config.ts
environments: {
  client: {
    optimizeDeps: {
      // resolves to the same node_modules/react/index.js as the bare `react`
      // the scanner already finds → two optimized chunks of one module.
      // (This mirrors what RSC frameworks add to keep React bundled while their
      //  own package is optimizeDeps-excluded; plugin-rsc's docs recommend the
      //  `<framework> > @vitejs/plugin-rsc` form for the same reason.)
      include: ["@vitejs/plugin-rsc > react"],
    },
  },
},

Comment that line out → clean cold start, single React chunk, no reload.

Observed, tracking the two chunks across the two passes:

chunk	pass 1 (cold)	pass 2 (after client-widget discovered)
react.js	canonical	alias → @vitejs_plugin-rsc_n_react.js
@vitejs_plugin-rsc_n_react.js	alias → react.js	canonical

Sequence on the first load:

1. The browser entry loads in pass 1 → import "react" binds to react.js = instance A.
2. The RSC payload references the client component → browser requests the client-package-proxy → first sighting of client-widget → re-optimization (pass 2).
3. Pass 2 flips the canonical → client-widget's import "react" binds to @vitejs_plugin-rsc_n_react.js = instance B.
4. A and B both live → Invalid hook call. react.js's content changed (real → alias) → hash changed → optimized dependencies changed. reloading; reload makes it pass-2-consistent and the error vanishes.

Reproduces ~4/5 cold starts (it's a race against the re-opt).

Expected: a source module should keep a stable canonical optimized chunk across re-optimization passes. Two include entries resolving to the same file must not be able to swap which one carries the real module between passes. The minimal, independently-testable invariant: dedup of same-resolved-id include entries should be deterministic across passes (keyed on resolved id, not on entry/iteration order).

The flip is not React-specific — duplicating react/jsx-runtime instead (x > react/jsx-runtime) reproduces the same crash framework-free, since the jsx-runtime chunk references React and the swap cascades into the React-instance mismatch. It's a property of the dedup mechanism, not of React.

---

Same bug, sharper surface: the react/jsx-runtime 't' interop error (in richer graphs)

In a real RSC framework graph (more nested include entries — a wrapper package that is itself optimizeDeps.exclude-d, a nested > @vitejs/plugin-rsc entry, react-error-boundary, etc.) the same instability shows up at ES-module link time instead of at render:

The requested module '/node_modules/.vite/deps/react_jsx-runtime.js?v=<B>'
does not provide an export named 't'

Key point: react/jsx-runtime is fully and correctly optimized here — a single chunk, needsInterop: true, whose final on-disk form does export { … as t }. So this is not the expected "you excluded / failed to optimize a CommonJS dep" behavior. t is rolldown's CJS-interop export; the failure is that a chunk produced by the re-optimization is served linking to a sibling chunk variant/version that doesn't have t.

What I measured in that graph (late-discovered package optimized in the second pass):

• On disk, the late package's chunk imports jsx-runtime relatively: import { t as … } from "./react_jsx-runtime.js" (no version).

• As served, that import is rewritten to an absolute, versioned URL whose version differs from the chunk's own URL version, every run:

  served chunk (its own ?v=)	its rewritten jsx-runtime import ?v=
  @…pkg.js?v=158f38f0	react_jsx-runtime.js?v=cd7f32ee
  @…pkg.js?v=72231b16	react_jsx-runtime.js?v=af0db615
  @…pkg.js?v=e31a0413	react_jsx-runtime.js?v=5021ae65

  i.e. the version on the chunk's own URL and the versions on its rewritten sibling imports come from different optimizer-metadata snapshots across the re-opt — the same cross-pass inconsistency as the canonical flip, just observed on a shared CJS sibling. When the referenced sibling version is still served → no error; when the re-opt has superseded it → the 't' SyntaxError.

I could not reduce this 't' surface to a deterministic minimal repro — framework-free, duplicating jsx-runtime surfaces as the render-time Invalid hook call (above) rather than the link-time 't'; the link-time form needs jsx-runtime to be a shared CJS chunk that a late chunk imports via its t export, a condition I only reproduced in the richer real-framework graph. I'm including it because it's the same root cause (a duplicated/flipped optimized chunk, inconsistent across passes), not a separate defect — and a fix for the canonical-stability invariant above should resolve it too.

Why this is one bug

Both surfaces are re-optimization failing to preserve referential consistency of what was already handed to the browser: the dependency graph grows on a request-time discovery, the new optimizer state is applied, but references from the previous state are still live (already-loaded chunks; rewritten sibling-import URLs). The render-time duplicate-React crash is the clean, minimal, independently-testable case; the link-time 't' error is the same instability surfacing on a shared CJS chunk in a more complex graph.

Note on the t export / "CommonJS must be optimized"

The CJS→ESM interop machinery itself (needsInterop, the t export) works as intended; React and react/jsx-runtime are optimized, not excluded. This is not a misconfiguration of "optimize your CommonJS deps" — it's re-optimization invalidating references that were already handed out.