RFC: Prerendering with Vite Preview Server

[edmundhung]

Problem

React Router's current prerendering directly imports the server bundle:

const build = await import(serverBuildPath);
const handler = createRequestHandler(build);

This requires the build runtime to match the deployment runtime if your code imports runtime-specific modules.

For example, when building with Node.js for Cloudflare Workers deployment, prerendering fails because Node.js can't import "cloudflare:workers" modules. You can't run the build in the Workers runtime either, since it doesn't support running Vite.

Proposed Solution

Use Vite's preview server instead of directly importing the server bundle.

This decouples the build environment from the target runtime:

• Build with whatever runtime can run Vite (typically Node.js)
• Preview server runs the built code in its target environment
• Prerendering makes HTTP requests to the preview server

No API changes - prerendering continues to work the same way from a user perspective. But we can start with an unstable flag for the community to test:

export default {
  future: {
    unstable_previewServerPrerendering: true,
  },
  async prerender() {
    return ["/", "/about"];
  },
};

Benefits

• Build with Node.js, deploy to any runtime: decouples the build environment from target runtime
• Uses the actual built code in a production-like environment for prerendering
• Preview server customizations from Vite plugins automatically apply to prerendering without additional integration
• React Router doesn't need runtime-specific logic

Implementation

Full implementation PR available at: #14650

Main changes:

• Start preview server before prerendering
• Make HTTP requests to preview server instead of importing the server bundle directly
• Cache route manifest and prerender path during build to avoid loading server modules

Trade-offs

• Requires maintaining Vite preview server support (Added in feat: add vite preview support #14507)
• Prerender data is passed via HTTP headers (~8KB limit). Routes with larger loader data will have loaders run twice during prerendering.
• Performance impact due to preview server startup time.