How the ssr Prop Works

As described in the How SSR Works guide, the router normally has no URL during SSR and only renders pathless routes. The ssr prop provides a pathname so path-based routes can also match during SSR:

// Server knows the requested URL and passes it to the router
<Router routes={routes} ssr={{ path: "/about" }} />

When ssr is provided, the router matches path-based routes against ssr.path just as it would match against the real URL on the client. Route params are extracted normally. Routes with loaders are skipped by default — the parent route renders as a shell, and loader content fills in after hydration.

Once the client hydrates, the real URL from the Navigation API takes over and ssr is ignored.

Example

Consider a route tree with a mix of static pages and loader-based routes:

const routes = [
  route({
    component: AppShell,
    children: [
      route({ path: "/", component: HomePage }),      // Matches ssr.path="/"
      route({ path: "/about", component: AboutPage }),// Matches ssr.path="/about"
      route({
        path: "/dashboard",
        component: DashboardPage,
        loader: dashboardLoader, // Skipped during SSR (has loader)
      }),
    ],
  }),
];

// With ssr={{ path: "/about" }}:
// - AppShell renders (pathless, no loader) ✓
// - AboutPage renders (path matches, no loader) ✓
// - DashboardPage would NOT render with ssr={{ path: "/dashboard" }}
//   because it has a loader

When to Use ssr

Use the ssr prop when your server or static site generator knows the URL being rendered and you want to include page-specific content in the SSR output. This is common for static site generation, but can also be used in dynamic SSR scenarios where the server can determine the URL at request time.

This is particularly useful for:

• Improving perceived performance by showing page content immediately instead of a blank shell
• SEO — search engine crawlers see the full page content rather than just the app shell
• Static site generation where each page is pre-rendered at a known path

Routes with Loaders

Routes with loaders are skipped by default during SSR. If your application has a server runtime that can execute loaders at request time, see the SSR with Loaders guide.

If you only need loaders to run at build time (not on the client), consider using React Server Components with SSG. RSC lets you fetch data on the server during the build and send the result as static HTML, without shipping loader code to the client.

Key Takeaways

• Use ssr to enable path-based route matching during SSR for richer server-rendered output
• Routes with loaders are skipped during SSR by default; the parent route renders as a shell and loader content fills in after hydration
• After hydration, the real URL from the Navigation API takes over and ssr is ignored