Hybrid Routing and Pre-rendering in React Router v7: The Ultimate Guide

📘 Hybrid Routing and Pre-rendering in React Router v7

React Router v7 enables flexible routing strategies that blend static site generation (SSG), server-side rendering (SSR), and client-side rendering (CSR)—all in one codebase.

⚙️ Pre-rendering Configuration

React Router lets you define pre-rendering behavior using the `ssr` and `prerender` flags in `react-router.config.ts`.

import type { Config } from "@react-router/dev/config";

export default {
  ssr: true,
  prerender: async ({ getStaticPaths }) => {
    let posts = await fakeGetPostsFromCMS();
    return ["/", "/blog", ...posts.map((post) => post.href)];
  },
} satisfies Config;

📦 Output Structure

When you build your project, React Router generates `.html` and `.data` files for each pre-rendered path inside the `build/client` directory.

• `index.html` – For direct document access
• `index.data` – For client-side navigations
• `__spa-fallback.html` – Used when only some routes are pre-rendered

📡 Pre-rendering with SSR Disabled

export default {
  ssr: false,
  prerender: ["/", "/about", "/services"],
} satisfies Config;

This setup produces static files without any server dependency. Great for platforms like Netlify or GitHub Pages.

🧩 SPA Fallback Support

You can mix pre-rendered routes with SPA fallback. React Router will generate `__spa-fallback.html` for unmatched routes.

export default {
  ssr: false,
  prerender: ["/", "/about-us"],
} satisfies Config;

Configure your host to serve this file for unknown routes to enable seamless SPA navigation:

# If '/' not pre-rendered
/*    /index.html   200

# If '/' is pre-rendered
/*    /__spa-fallback.html   200

❌ Invalid Config Warnings

• `action` and `headers` are not allowed when `ssr: false`
• `loader` is only allowed on root route in SPA mode
• `loader` is allowed on any matched pre-rendered path

🧠 Summary: Hybrid Routing = Ultimate Flexibility

• Mix SSR, CSR, and SSG in the same project
• Boost SEO and performance
• Host on static or dynamic platforms

With React Router v7, you're no longer forced to choose between SEO or performance. You get the best of all rendering worlds.

📥 Try It Now

npm install react-router

Need help integrating this in your project? Reach out—we’d love to help you go hybrid!