File-system routing requires `ssr: true` for the dev server (lift this limitation)

[uhyo]

Summary

Built-in file-system routing (the experimental fsRoutes option, added in #123) only renders in vite dev when ssr: true is set. With the default ssr: false, the dev server renders the app shell but the page content never appears. Production builds (vite build) are unaffected and work with ssr either way.

We currently work around this by requiring/documenting ssr: true for fs-routing. This issue tracks lifting that limitation so ssr: false works in dev too.

Root cause

fs-routing renders pages through FUNSTACK Router's <Router> (a client component) and passes the page components as server-component route data:

<Router routes={[{ path: "/about", component: <AboutPage /> }]} ssr={{ path }} />

• In a production build (ssr: false), the RSC payload is pre-rendered at build time, so the server components in routes are rendered to their output and serialized. ✅

• In vite dev with ssr: false, the app is rendered on the client from the RSC stream. @vitejs/plugin-rsc serializes the server-component route data as an eval'd dev-JSX source reference (a $E…function AboutPage(){ _jsxDEV(...) } entry in the flight data). When the browser evaluates it, the jsxDEV import resolves to the client's optimized react/jsx-runtime, which doesn't export it:

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

  React's error boundary then renders the "Unexpected Error" shell, so no page content appears.

• In vite dev with ssr: true, pages are rendered on the server, so the broken client eval path is never taken. ✅

This is not specific to the fsRoutes codegen — the same failure reproduces with the equivalent hand-written userland pattern (module-level routes with component: <Page />, ssr: false). It's an interaction between "server components passed as data to a client component" and @vitejs/plugin-rsc's dev serialization.

Reproduction

1. Configure fsRoutes (or a hand-written <Router routes={[{ component: <ServerPage /> }]} />) without ssr: true.
2. vite dev, open any route in a browser.
3. The shell loads but page content is missing; the console shows the react/jsx-runtime jsxDEV/'t' export error above.

packages/static/e2e/tests-dev/fs-routing.spec.ts reproduces this when the fixture's ssr is false.

Possible directions

• Render the matched route on the server even when ssr: false in dev (mirror the production pre-render path), so the client receives rendered output rather than an eval'd server-component reference.
• Investigate whether @vitejs/plugin-rsc can serialize server components passed as client-component props consistently between dev and build (upstream fix or configuration).
• Align the dev jsx runtime so the eval'd dev-JSX (jsxDEV) resolves correctly on the client.

Workaround (current)

Set ssr: true when using fsRoutes. This is documented in the File-System Routing guide and used by the example and e2e fixture.

Related: #123

[uhyo]

Investigation findings

I dug into the dev-server failure and the root cause turns out to be a bit different from the original diagnosis — sharing in case it's useful for the writeup.

TL;DR

The crash isn't really about jsxDEV or the JSX runtime. The t in … does not provide an export named 't' is vite's optimize-deps interop name for the react/jsx-runtime CommonJS module factory — not React's jsxDEV. The failure is a vite dependency pre-bundling (optimize-deps) hash/interop mismatch that surfaces through the RSC client render.

Evidence

In the client's optimized deps:

// node_modules/.vite/deps/react_jsx-runtime.js
var require_jsx_runtime = __commonJSMin((exports, module) => {
  module.exports = require_react_jsx_runtime_development();
});
export default require_jsx_runtime();
export { require_jsx_runtime as t };   // <-- 't' is the CJS module factory, not jsxDEV

// node_modules/.vite/deps/@funstack_router.js
import { t as require_jsx_runtime } from "./react_jsx-runtime.js";  // the router chunk consumes 't'

@funstack/router is a pre-built package whose dist is compiled with the production automatic JSX runtime (react/jsx-runtime → jsx/jsxs, zero jsxDEV). So react/jsx-runtime is legitimately on the client even under vite dev — vite doesn't recompile a dependency's published dist with the dev runtime. The optimized router chunk imports the jsx-runtime factory under vite's interop name t. When the optimizer re-bundles mid-session, an already-loaded chunk ends up importing t from a react_jsx-runtime.js?v=<stale-hash> whose export shape no longer matches → the error. React's error boundary then turns the failed dynamic import into the "Unexpected Error" shell.

Why it's specific to fs-routes (and reproduces only on a cold start)

• fsRoutes + ssr: false makes the client render the whole app — including the @funstack/router client component and all route data — from the RSC stream on first paint. That pulls @funstack/router into the client graph and triggers dep (re)optimization during the initial render, which is exactly when the stale-chunk import race bites.
• Normal ssr: false apps (single/multi-entry) don't put @funstack/router on the first client render, so the fragile interop edge (@funstack_router.js → react_jsx-runtime.js t) is never exercised.
• I reproduced the exact error on the very first cold vite dev start, but could not reproduce it on subsequent cold starts (even at b6dbea5 with a cleared .vite) — consistent with an optimize-deps discovery/timing race rather than a static bug.
• For completeness: the same dev $E / _jsxDEV server-component debug serialization is present in normal apps too, and "a server component passed as a plain prop to a client component" renders fine — so neither of those is the actual trigger.

[uhyo]

Fix Found

Vite docs says that CommonJS dependencies should not be excluded from optimization..

However, our plugin has this line:

        // Since code includes imports to virtual modules, we need to exclude
        // us from Optimize Deps.
        config.optimizeDeps.exclude.push("@funstack/static");

This broke the rule above by excluding react depended from @funstack/static which is a CommonJS module.
So a fix is:

        // Since code includes imports to virtual modules, we need to exclude
        // us from Optimize Deps.
        config.optimizeDeps.exclude.push("@funstack/static");
        // Nested CommonJS deps should still be optimized (see issue #124):
        config.optimizeDeps.include.push("@funstack/static > react");

[uhyo]

Note: how to reproduce the issue

node_modules/.vite must be deleted to reproduce the issue. This deletes the Optimize Deps cache and reproduces a cold start.

Note that the Vite process must be restarted for the deletion to take effect.