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.

[nahyeongjin1]

I'd like to share my use case that would benefit from this feature.

My Setup

• Project: Technical blog built with React Router v7 (framework mode)
• Deployment: Netlify with @netlify/vite-plugin-react-router
• Features needed: SSR (for authentication + comments) + prerender (for blog posts)

The Problem

With @netlify/vite-plugin-react-router, any form of prerender configuration causes the build to fail:

// Option 1: Simple flag
prerender: true,

// Option 2: Explicit paths
async prerender() {
  return [
    '/',
    '/posts',
    '/projects',
    '/bookmarks',
    '/about',
    ...(await mdx.paths()),
  ];
},

Regardless of ssr: true or ssr: false, enabling prerender in any way results in:

[react-router] Server build file not found in manifest

This is the same issue described in #14096.

Workaround Attempt

I also tried the workaround from #13226 (adding virtual:react-router/server-build to rollup input):

export default defineConfig(({ isSsrBuild }) => ({
  build: {
    rollupOptions: isSsrBuild
      ? { input: ['virtual:react-router/server-build'] }
      : undefined,
  },
  plugins: [reactRouter(), tsconfigPaths(), netlifyReactRouter(), netlify()],
}));

This still fails with the same error — the Netlify plugin appears to override or conflict with the rollup configuration.

Why This Matters

I had to disable prerender entirely and rely on SSR-only, which means every request hits Netlify Functions instead of serving static HTML.

For a blog with mostly static content (MDX files), prerendering would significantly improve performance and reduce serverless function invocations. The proposed solution of using Vite preview server elegantly decouples the build environment from the deployment runtime.

Looking forward to this landing!