Only import the top-level index route when SSRing SPA mode's index.html

jenseng · jenseng · commit 488431a13045 · 2025-02-13T14:51:46.000-07:00
Since we only actually render the top-level index route in SPA mode, we
don't need to import any other routes in the server bundle; the bundle is
solely used to generate the index.html file, and is subsequently discarded.

This should speed up SPA mode builds and make them less error prone; often
times apps use libraries that are not SSR-capable (e.g. referencing window
in the module scope). By excluding all other routes (and their deps), we
make the index.html render more likely to be successful and less likely to
require a bunch of externals/shimming shenanigans in vite.config.js.
diff --git a/integration/vite-spa-mode-test.ts b/integration/vite-spa-mode-test.ts
@@ -913,4 +913,100 @@ test.describe("SPA Mode", () => {
       expect(viteManifestFiles).toEqual(["manifest.json"]);
     });
   });
+
+  test("only imports top-level route modules when SSRing index.html", async ({ page }) => {
+    let fixture = await createFixture({
+      spaMode: true,
+      files: {
+        "react-router.config.ts": reactRouterConfig({
+          ssr: false,
+        }),
+        "vite.config.ts": js`
+          import { defineConfig } from "vite";
+          import { reactRouter } from "@react-router/dev/vite";
+
+          export default defineConfig({
+            build: { manifest: true },
+            plugins: [reactRouter()],
+          });
+        `,
+        "app/routeImportTracker.ts": js`
+          // this is kinda silly, but this way we can track imports
+          // that happen during SSR and during CSR
+          export async function logImport(url: string) {
+            try {
+              const fs = await import("node:fs");
+              const path = await import("node:path");
+              fs.appendFileSync(path.join(process.cwd(), "ssr-route-imports.txt"), url + "\n");
+            }
+            catch (e) {
+              (window.csrRouteImports ??= []).push(url);
+            }
+          }
+        `,
+        "app/root.tsx": js`
+          import { Links, Meta, Outlet, Scripts } from "react-router";
+          import { logImport } from "./routeImportTracker";
+          logImport("app/root.tsx");
+
+          export default function Root() {
+            return (
+              <html lang="en">
+                <head>
+                  <Meta />
+                  <Links />
+                </head>
+                <body>
+                  hello world
+                  <Outlet />
+                  <Scripts />
+                </body>
+              </html>
+            );
+          }
+        `,
+        "app/routes/_index.tsx": js`
+          import { logImport } from "../routeImportTracker";
+          logImport("app/routes/_index.tsx");
+
+          export default function Component() {
+            return "index";
+          }
+        `,
+        "app/routes/about.tsx": js`
+          import * as React  from "react";
+          import { logImport } from "../routeImportTracker";
+          logImport("app/routes/about.tsx");
+
+          export default function Component() {
+            const [mounted, setMounted] = React.useState(false);
+            React.useEffect(() => setMounted(true), []);
+
+            return (
+              <>
+                {!mounted ? <span>Unmounted</span> : <span data-mounted>Mounted</span>}
+              </>
+            );
+          }
+        `,
+      },
+    });
+
+    let importedRoutes = (await fs.promises.readFile(path.join(fixture.projectDir, "ssr-route-imports.txt"), "utf-8")).trim().split("\n");
+    expect(importedRoutes).toStrictEqual([
+      "app/root.tsx",
+      "app/routes/_index.tsx"
+      // we should NOT have imported app/routes/about.tsx
+    ]);
+
+    appFixture = await createAppFixture(fixture);
+    let app = new PlaywrightFixture(appFixture, page);
+    await app.goto("/about");
+    await page.waitForSelector("[data-mounted]");
+    // @ts-expect-error
+    expect(await page.evaluate(() => window.csrRouteImports)).toStrictEqual([
+      "app/root.tsx",
+      "app/routes/about.tsx"
+    ]);
+  });
 });
diff --git a/packages/react-router-dev/vite/plugin.ts b/packages/react-router-dev/vite/plugin.ts
@@ -456,19 +456,37 @@ export const reactRouterVitePlugin: ReactRouterVitePlugin = () => {
       : // Otherwise, all routes are imported as usual
         ctx.reactRouterConfig.routes;
 
+    let isSpaMode =
+      !ctx.reactRouterConfig.ssr && ctx.reactRouterConfig.prerender == null;
+
+    let routeIdsToImport = new Set(Object.keys(routes));
+    if (isSpaMode) {
+      // In SPA mode, we only pre-render the top-level index route; for all
+      // other routes we stub out their imports, as they (and their deps) may
+      // not be compatible with server-side rendering. This also helps keep
+      // the build fast
+      routeIdsToImport = getRootRouteIds(routes);
+    }
+
     return `
     import * as entryServer from ${JSON.stringify(
       resolveFileUrl(ctx, ctx.entryServerFilePath)
     )};
     ${Object.keys(routes)
       .map((key, index) => {
         let route = routes[key]!;
-        return `import * as route${index} from ${JSON.stringify(
-          resolveFileUrl(
-            ctx,
-            resolveRelativeRouteFilePath(route, ctx.reactRouterConfig)
-          )
-        )};`;
+        if (routeIdsToImport.has(key)) {
+          return `import * as route${index} from ${JSON.stringify(
+            resolveFileUrl(
+              ctx,
+              resolveRelativeRouteFilePath(route, ctx.reactRouterConfig)
+            )
+          )};`;
+        } else {
+          // we're not importing the route since we won't be rendering
+          // it via SSR; just stub it out
+          return `const route${index} = { default: () => null };`;
+        }
       })
       .join("\n")}
       export { default as assets } from ${JSON.stringify(
@@ -482,9 +500,7 @@ export const reactRouterVitePlugin: ReactRouterVitePlugin = () => {
       )};
       export const basename = ${JSON.stringify(ctx.reactRouterConfig.basename)};
       export const future = ${JSON.stringify(ctx.reactRouterConfig.future)};
-      export const isSpaMode = ${
-        !ctx.reactRouterConfig.ssr && ctx.reactRouterConfig.prerender == null
-      };
+      export const isSpaMode = ${isSpaMode};
       export const publicPath = ${JSON.stringify(ctx.publicPath)};
       export const entry = { module: entryServer };
       export const routes = {
@@ -1198,7 +1214,7 @@ export const reactRouterVitePlugin: ReactRouterVitePlugin = () => {
             ctx.reactRouterConfig.prerender !== false
           ) {
             // If we have prerender routes, that takes precedence over SPA mode
-            // which is ssr:false and only the rot route being rendered
+            // which is ssr:false and only the root route being rendered
             await handlePrerender(
               viteConfig,
               ctx.reactRouterConfig,
@@ -2087,13 +2103,20 @@ function validatePrerenderedHtml(html: string, prefix: string) {
   }
 }
 
-type ServerRoute = ServerBuild["routes"][string] & {
-  children: ServerRoute[];
+// Just the minimum necessary to unflatten manifests generically (e.g. RouteManifest vs. ServerBuild["routes"])
+type ServerRoute = {
+  id: string;
+  parentId?: string;
+  path?: string;
+  caseSensitive?: boolean;
+  index?: boolean;
 };
 
-// Note: Duplicated from react-router/lib/server-runtime
-function groupRoutesByParentId(manifest: ServerBuild["routes"]) {
-  let routes: Record<string, Omit<ServerRoute, "children">[]> = {};
+// Note: Adapted from react-router/lib/server-runtime
+function groupRoutesByParentId<T extends ServerRoute>(
+  manifest: Record<string, T | undefined>
+) {
+  let routes: Record<string, T[]> = {};
 
   Object.values(manifest).forEach((route) => {
     if (route) {
@@ -2108,36 +2131,52 @@ function groupRoutesByParentId(manifest: ServerBuild["routes"]) {
   return routes;
 }
 
-// Note: Duplicated from react-router/lib/server-runtime
-function createPrerenderRoutes(
-  manifest: ServerBuild["routes"],
+// Note: Adapted from react-router/lib/server-runtime
+function createRoutes<T extends ServerRoute, T2 extends Partial<T> = T>(
+  manifest: Record<string, T | undefined>,
+  mapRoute: (route: T) => T2 = (route) => route as unknown as T2,
   parentId: string = "",
-  routesByParentId: Record<
-    string,
-    Omit<ServerRoute, "children">[]
-  > = groupRoutesByParentId(manifest)
-): DataRouteObject[] {
-  return (routesByParentId[parentId] || []).map((route) => {
-    let commonRoute = {
-      // Always include root due to default boundaries
-      hasErrorBoundary:
-        route.id === "root" || route.module.ErrorBoundary != null,
-      id: route.id,
-      path: route.path,
-      loader: route.module.loader ? () => null : undefined,
-      action: undefined,
-      handle: route.module.handle,
+  routesByParentId = groupRoutesByParentId(manifest),
+) {
+  return (routesByParentId[parentId] || []).map((route): T2 => {
+    return {
+      ...(route.index
+        ? { index: true }
+        : {
+            caseSensitive: route.caseSensitive,
+            children: createRoutes(
+              manifest,
+              mapRoute,
+              route.id,
+              routesByParentId,
+            ),
+          }),
+      ...mapRoute(route),
     };
-
-    return route.index
-      ? {
-          index: true,
-          ...commonRoute,
-        }
-      : {
-          caseSensitive: route.caseSensitive,
-          children: createPrerenderRoutes(manifest, route.id, routesByParentId),
-          ...commonRoute,
-        };
   });
 }
+
+function createPrerenderRoutes(
+  manifest: ServerBuild["routes"]
+): DataRouteObject[] {
+  return createRoutes(manifest, (route) => ({
+    // Always include root due to default boundaries
+    hasErrorBoundary: route.id === "root" || route.module.ErrorBoundary != null,
+    id: route.id,
+    path: route.path,
+    loader: route.module.loader ? () => null : undefined,
+    action: undefined,
+    handle: route.module.handle,
+  }));
+}
+
+/**
+ * Return the route ids associated with the top-level index route
+ *
+ * i.e. "root", the top-level index route's id, and (if applicable) the ids of
+ * any top-level layout/path-less routes in between
+ */
+function getRootRouteIds(manifest: RouteManifest): Set<string> {
+  const matches = matchRoutes(createRoutes(manifest), "/");
+  return new Set(matches?.filter(Boolean).map((m) => m.route.id) || []);
+}
