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

[uhyo]

Describe the bug

🤖 AI Disclosure: Claude Code has written up majority of this issue and most of the reproduction README. I, as a human, still take responsibility for it.

Summary

When two optimizeDeps.include entries resolve to the same module (e.g. react and @vitejs/plugin-rsc > react, where @vitejs/plugin-rsc can be any package that peer-depends on react), the optimizer emits two chunks for it — one holds the real 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.

chunk	pass 1 (cold)	pass 2 (after re-optimization)
react.js	canonical	alias → @vitejs_plugin-rsc_n_react.js
@vitejs_plugin-rsc_n_react.js	alias → react.js	canonical

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.

Detailed explanation can be found in the reproduction repository's README.

Context

I've been developing a React framework based on @vitejs/plugin-rsc. This issue originally surfaced as a framework bug, but a thorough investigation made us believe that this is a Vite issue.

The repro still uses @vitejs/plugin-rsc because it is the way we are aware of for reliably reproducing the issue, but we believe this issue is in Vite's Deps Optimization, hence a bug report in this repo.

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.

Side Note: possible another form of this bug

Initially this bug surfaced as a different error like this:

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

a severer ES Modules link time error. This version of error is not included in this bug report because (1) we couldn't reproduce this without involving our framework and (2) we are not sure whether they are truly same origin. Read more about this at uhyo/funstack-static#124 and uhyo/funstack-static#128.

Reproduction

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

Steps to reproduce

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

System Info

System:
    OS: Linux 6.18 Ubuntu 22.04.1 LTS 22.04.1 LTS (Jammy Jellyfish)
    CPU: (16) x64 AMD Ryzen 7 PRO 6850U with Radeon Graphics
    Memory: 12.37 GB / 15.01 GB
    Container: Yes
    Shell: 5.1.16 - /bin/bash
  Binaries:
    Node: 24.13.1 - /home/uhyo/.volta/tools/image/node/24.13.1/bin/node
    Yarn: 4.1.1 - /home/uhyo/.volta/tools/image/yarn/4.1.1/bin/yarn
    npm: 11.4.2 - /home/uhyo/.volta/tools/image/npm/11.4.2/bin/npm
    pnpm: 10.30.1 - /home/uhyo/.volta/bin/pnpm
    Deno: 2.2.1 - /home/uhyo/.deno/bin/deno
  npmPackages:
    @vitejs/plugin-react: latest => 6.0.3 
    @vitejs/plugin-rsc: latest => 0.5.27 
    vite: ^8.0.16 => 8.1.0

Used Package Manager

pnpm

Logs

No response

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Make sure this is a Vite issue and not a framework-specific issue. For example, if it's a Vue SFC related bug, it should likely be reported to vuejs/core instead.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion or join our Discord Chat Server.
• The provided reproduction is a minimal reproducible example of the bug.

[sapphi-red]

I'm not sure if I understand the issue. What is the expected behavior and the actual behavior? If it is the "broken" state before the auto-reload, it is kind of expected because the reload is there to fix that.

[uhyo]

@sapphi-red Sorry for this complex report, and thank you for taking time 🥹 Let me explain.

Yes, it is only about the state before reload, so I understand if you determine that this is an expected (or at least not worth improving) behavior.

However, I still reported this for a possible chance of improving this; maybe I should have framed this as a request for improvement rather than a bug report.

---

The real pain I'm experiencing as an author of a Vite-based framework is the users facing the bad developer experience that originates from the reported behavior: a strange React error visible for only a moment, then an automatic reload.

While the reload does fix the problem, this kind of issue critically damages the first impression of my Vite-based framework, which is why I'd be super glad if this behavior gets fixed at the Vite side.

Currently we need to workaround this on the framework side by traversing node_modules for all packages that has React has a peer dependency.

---

On actual VS expected behavior, the actual behavior is:

chunk	pass 1 (cold)	pass 2 (after re-optimization)
react.js	canonical	alias → @vitejs_plugin-rsc_n_react.js
@vitejs_plugin-rsc_n_react.js	alias → react.js	canonical

while the expected behavior is:

chunk	pass 1 (cold)	pass 2 (after re-optimization)
react.js	canonical	canonical
@vitejs_plugin-rsc_n_react.js	alias → react.js	alias → react.js

Let me explain; when you open the repro project in your browser, you see several files loaded, including react.js and @vitejs_plugin-rsc_n_react.js.

The timeline is:

1. Visit Vite's dev server with your browser
2. react.js is loaded via framework client entrypoint ← this is pass 1, so a canonical React instance is loaded
3. /@id/__x00__virtual:vite-rsc/client-package-proxy/client-widget is loaded which triggers re-optimization
4. Deps are re-optimized (flips the canonical React instance)
5. @vitejs_plugin-rsc_n_react.js is loaded ← we are already in pass 2, so another canonical React instance loaded
6. Client-side error due to double React instance

The error is triggered due to pass 1 and pass 2 being mixed during a single client app boot (before the reload kicks in).

---

Hope this explains everything. Yet it's up to you whether this is even a bug, expected behavior, or something Vite won't support. Thank you 🙂

[hi-ogawa]

This issue likely belongs to rsc plugin. The re-optimization can be avoided either by optimizeDeps.include: ["client-widget"] or optimizeDeps.entries: ["./src/root.tsx"]. For example, Waku has this optimizeDeps.entries https://github.com/wakujs/waku/blob/0ac0b94123d7bd094b45fb7818e1045b4446303d/packages/waku/src/lib/vite-plugins/environments.ts#L57-L63

I think there is a reason why rsc plugin cannot do this automatically, but it's worth mentioning the gotcha in doc (rsc plugin readme).