fix(ssr): preload client reference modules before first SSR render

[gagipro]

Summary

Fixes #256 — the first HTTP request after vinext start always returns 500.

Problem

On cold start, client reference modules ("use client" components) are loaded lazily via
async import() through @vitejs/plugin-rsc's setRequireModule({ load }). When handleSsr
runs renderToReadableStream on the first request, React SSR tries to render the HTML shell
but the client component imports haven't resolved yet. With no <Suspense> boundary wrapping
the root, React cannot render a fallback and rejects with undefined, causing a 500.

All subsequent requests work because memoize() in setRequireModule caches resolved modules.

Fix

Eagerly preload all client reference modules at the start of handleSsr, before
renderToReadableStream runs:

import * as _clientRefs from "virtual:vite-rsc/client-references";

export async function handleSsr(rscStream, navContext, fontData) {
  // Preload client refs so first SSR render can resolve them synchronously
  if (_clientRefs?.default && globalThis.__vite_rsc_client_require__) {
    await Promise.all(
      Object.keys(_clientRefs.default).map((id) =>
        globalThis.__vite_rsc_client_require__(id).catch?.(() => {})
      )
    );
  }
  // ... rest of handleSsr unchanged
}

The virtual:vite-rsc/client-references module (provided by @vitejs/plugin-rsc) exposes
the map of all client component IDs. The __vite_rsc_client_require__ global is already set
by initialize() before handleSsr is called.

Scope

• 1 file changed, 16 insertions
• packages/vinext/src/server/app-dev-server.ts — inside generateSsrEntry() template
• No changes to @vitejs/plugin-rsc or any other package

Testing

Verified on a production vinext app with 11 client component references:

• Before fix: first request after restart → 500 (100% reproducible)
• After fix: 5/5 restart cycles → 200 on first request, all routes (/, /login, /dashboards, /datasources, /dashboards/[id]) return 200

Notes

• The preload runs once per request but the memoize() cache means only the first call per ID
  does actual work. The overhead on subsequent requests is negligible (synchronous Map lookups).
• The defensive ?.default and ?.catch guards ensure the fix is safe if @vitejs/plugin-rsc
  changes its export shape in the future.
• This fix is in the generated SSR entry (template literal in generateSsrEntry()), so it
  affects both dev and production SSR.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/vinext@257

commit: f0cc47f

[hi-ogawa]

This looks like a reasonable idea, but I don't think this saves other (edge) cases where user's are manually writing React.lazy component inside own client component. Indeed, what implicitly happens with "use client" (client component) is that basically it auto-wraps the exported component to work like React.lazy-ed component. It might worth testing with artificially slow lazy component. Also it's not impossible that there could be a react bug around SSR and lazy component as I've seen once before and sent issues.

[gagipro]

Thanks for the review @hi-ogawa — good points.

You're right that this fix only covers the "use client" references that vinext itself auto-wraps (via @vitejs/plugin-rsc). It doesn't help if someone manually writes React.lazy(() => import(...)) inside their own client component — those lazy imports would still race on the first SSR.

A couple of questions:

1. Do you have a link to the React SSR + lazy component issues you mentioned? Would be helpful to check whether it's the same root cause or a separate React-level bug.
2. Do you have a concrete repro for the manually-written React.lazy edge case in a vinext app? If so, I can add a test with an artificially slow lazy component as you suggested. Otherwise, would you be open to tracking that as a follow-up issue?

This PR targets the common case (every "use client" component → 500 on first request, 100% repro rate). Happy to extend the fix or open a separate issue for the manual React.lazy edge case.

[hi-ogawa]

Just in case, to clarify, I was only commenting as I maintain@vitejs/plugin-rsc. If the fix like this is relevant for other vite rsc framework, then it might makes sense to expose such preload utility instead of vinext directly using (semi) internal virtual modules.

Do you have a link to the React SSR + lazy component issues you mentioned? Would be helpful to check whether it's the same root cause or a separate React-level bug.

The one I mentioned is already fixed facebook/react#33937. Sorry, my comment wasn't really based, but I thought it's worth mentioning.

Do you have a concrete repro for the manually-written React.lazy edge case in a vinext app?

I'd imagine something like this React.lazy(() => new Promise(r => setTimeout(r, 1000)).then(() => ({ default: () => <div />}))) could theoretically hit a similar lazy + suspense logic on ssr.

[gagipro]

Thanks for the clarification @hi-ogawa. After looking at this more carefully, the React.lazy scenario is a distinct code path — React.lazy creates a fresh thenable each time (not going through the memoize() cache in setRequireModule), so:

• With a <Suspense> boundary: React SSR streams it correctly (fallback → content)
• Without <Suspense>: it would fail on every request, which is a user-side missing-Suspense issue, not something the framework should silently fix

So this PR correctly scopes to the "use client" auto-wrapping path, which is the only case that exhibits the "first-request-only 500" behavior.

The 500-on-first-request is a hard blocker for production deployments, and the virtual module import is already public API (used in the generated SSR entry) — would you be OK merging this as a short-term fix? Happy to contribute a preloadClientReferences() API in @vitejs/plugin-rsc as a follow-up once this lands, so other frameworks benefit too.

[gagipro]

Rebasing this PR against current main — the entries/ refactor (#377, #378, #379) moved generateSsrEntry from the deleted app-dev-server.ts into packages/vinext/src/entries/app-ssr-entry.ts. The fix is the same 16-line preload block, just applied to the new file.

Re-verified the bug still exists on v0.0.27 (latest release):

Cycle	First request	Server log
Without fix	HTTP 500 (0.14s)	[vinext] Server error: undefined
With fix	HTTP 200 (0.16s)	No errors

Tested 5 restart cycles with concurrent requests (/, /login, /dashboards/[id]) — all 200s with the fix, consistent first-request 500 without it.

Force-pushing the rebased branch now.

[james-elicx]

/bigbonk review

[ask-bonk]

UnknownError: "Overloaded"

github run

[ask-bonk]

@james-elicx Bonk workflow failed. Check the logs for details.

View workflow run · To retry, trigger Bonk again.

[james-elicx]

/bigbonk review

[ask-bonk]

UnknownError: "Overloaded"

github run

[james-elicx]

Thanks for the fix — the bug is real and the root cause analysis is correct. A few things to resolve before merging.

Blocking

No regression test

Per the project guidelines, tests come first. There's no test covering the cold-start behavior. Without one, this can silently regress. Please add a case to the relevant test file (likely tests/app-router.test.ts or tests/features.test.ts) that verifies the first request after server start returns 200.

Silent error swallowing on preload failure

globalThis.__vite_rsc_client_require__(id).catch?.(() => {})

If a module fails to load here, the error is discarded, and renderToReadableStream will fail with a confusing/missing error instead of the real cause. At minimum, log in non-production:

globalThis.__vite_rsc_client_require__(id).catch?.((err) => {
  if (process.env.NODE_ENV !== "production") {
    console.warn("[vinext] failed to preload client ref:", id, err);
  }
})

Non-blocking

Prod-server parity check

AGENTS.md notes that server/prod-server.ts has its own SSR/routing logic that must be kept in sync with the SSR entry. Worth confirming the same cold-start issue doesn't exist on that path (or noting explicitly that it doesn't apply).

Unnecessary optional chaining

• _clientRefs?.default — if this virtual module always exists in the build, the ?. on the module itself is dead code.
• .catch?.() — native Promises always have .catch; the optional chaining adds no safety here.

Neither is a bug, just noise.