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

jenseng · jenseng · commit cb3cfece2af9 · 2025-02-18T13:43:33.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
@@ -1067,4 +1067,100 @@ test.describe("SPA Mode", () => {
       });
     });
   });
+
+  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
@@ -597,19 +597,37 @@ export const reactRouterVitePlugin: ReactRouterVitePlugin = () => {
       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(
@@ -626,7 +644,7 @@ export const reactRouterVitePlugin: ReactRouterVitePlugin = () => {
       export const basename = ${JSON.stringify(ctx.reactRouterConfig.basename)};
       export const future = ${JSON.stringify(ctx.reactRouterConfig.future)};
       export const ssr = ${ctx.reactRouterConfig.ssr};
-      export const isSpaMode = ${isSpaModeEnabled(ctx.reactRouterConfig)};
+      export const isSpaMode = ${isSpaMode};
       export const prerender = ${JSON.stringify(prerenderPaths)};
       export const publicPath = ${JSON.stringify(ctx.publicPath)};
       export const entry = { module: entryServer };
@@ -1394,7 +1412,7 @@ export const reactRouterVitePlugin: ReactRouterVitePlugin = () => {
 
           if (isPrerenderingEnabled(ctx.reactRouterConfig)) {
             // 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,
@@ -2587,6 +2605,17 @@ function groupRoutesByParentId(manifest: GenericRouteManifest) {
   return routes;
 }
 
+/**
+ * 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: GenericRouteManifest): Set<string> {
+  const matches = matchRoutes(createPrerenderRoutes(manifest), "/");
+  return new Set(matches?.filter(Boolean).map((m) => m.route.id) || []);
+}
+
 // Create a skeleton route tree of paths
 function createPrerenderRoutes(
   manifest: GenericRouteManifest,
