Improvements to ssr:false + prerender scenarios #12948

brophdawg11 · 2025-02-04T18:49:03Z

@brookslybrand and I did a deep dive on some of the current nuances/pain points with ssr:false and prerender scenarios. In Remix v2, we only had the ssr config so ssr:false alone implied "SPA Mode". When we added prerender in RR v7, we didn't quite nail all of the changes to ensure that differences between ssr:false versus true "SPA Mode" were correctly updated.

"SPA Mode" means a single HTML page capable of hydrating for any route. It can do this because it only renders the root route HydrateFallback on the server and then loads the proper client-side matched routes via route.lazy during hydration. This is what you get with ssr:false and no prerender config.
In Remix v2 and so far in RRv7, we didn't allow any loaders when in SPA mode. This PR updates that logic so that you can have a root loader because it does always run on the server and makes loaderData available to HydrateFallback as an optional prop so you can render a more full-featured loading page.
Once you add a prerender config, you're opting into pre-rendering non-SPA (effectively MPA) pages for those routes - and those will be able to run the loaders below the root and prerender complete HTML docs in SSG fashion. Those HTML docs still hydrate into client-side-navigable applications.
That left a small gap in real world use cases where once you added ssr:false + prerender:['/'], you lost your ability to serve SPA mode any longer because the main index.html file was now an MPA that included routes/_index. In these scenarios, prerender will now output a special __spa-fallback__.html file that you can confiugure your static server to serve for any paths you didn't prerender. This is powerful because you can still use ssr:false, fully prerender some paths for perf/SEO, and still allow users to enter your app on any other path via the SPA fallback.

A few other small updates:

We now also throw errors for action/header exports when using ssr:false
Our dev server will now 404 on non-prerendered routes when using ssr:false and a prerender config to better align with production behavior

TODO:

Docs

…render combinations

changeset-bot · 2025-02-04T18:49:09Z

🦋 Changeset detected

Latest commit: 9c8a9bf

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
react-router	Major
@react-router/dev	Major
@react-router/architect	Major
@react-router/cloudflare	Major
react-router-dom	Major
@react-router/express	Major
@react-router/node	Major
@react-router/serve	Major
@react-router/fs-routes	Major
@react-router/remix-routes-option-adapter	Major
create-react-router	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

brophdawg11 · 2025-02-06T20:28:23Z

packages/react-router-dev/vite/plugin.ts

+            if (route.id === "root" && exp === "loader") {
+              return false;
+            }


Allow the root route to have a loader in SPA mode

brophdawg11 · 2025-02-06T20:30:07Z

packages/react-router-dev/vite/plugin.ts

-      (Array.isArray(reactRouterConfig.prerender) &&
-        reactRouterConfig.prerender.length === 1 &&
-        reactRouterConfig.prerender[0] === "/"))


This went a bit too far - ssr:false, prerender:['/'] is an explicit opt-into prerendering the / route and should trigger full SSG of the / route and prerender past the root.

brophdawg11 · 2025-02-06T20:30:59Z

packages/react-router-dev/vite/plugin.ts

+  let request = new Request(`http://localhost${reactRouterConfig.basename}`, {
+    headers: {
+      // Enable SPA mode in the server runtime and only render down to the root
+      "X-React-Router-SPA-Mode": "yes",


We use this during build-time request handling now so we can render a SPA fallback even when build.isSpaMode is false because we're prerendering some MPA pages

brophdawg11 · 2025-02-06T20:31:28Z

packages/react-router/lib/server-runtime/build.ts

@@ -21,7 +21,11 @@ export interface ServerBuild {
  assetsBuildDirectory: string;
  future: FutureConfig;
  ssr: boolean;
+  /**
+   * @deprecated This is now done via a custom header during prerendering
+   */


No longer used by our server - but since ServerBuild is arguably public API we can just deprecate it

brophdawg11 · 2025-02-06T20:31:51Z

packages/react-router-dev/vite/plugin.ts

-  validatePrerenderedResponse(response, html, "SPA Mode", "/");
-  validatePrerenderedHtml(html, "SPA Mode");


Inlined these assertions for clarity

brophdawg11 · 2025-02-06T20:33:19Z

packages/react-router-dev/vite/plugin.ts

+  // they can serve.  Otherwise it can be the main entry point.
+  let isPrerenderSpaFallback = build.prerender.includes("/");
+  let filename = isPrerenderSpaFallback
+    ? "__spa-fallback__.html"


Write out this spa fallback file when the user chose ssr:false + prerender:['/'] as a way for them to load/hydrate into non-prerendered paths without a runtime server

brophdawg11 · 2025-02-06T20:34:18Z

packages/react-router-dev/vite/plugin.ts

-  let routesToPrerender: string[];
-  if (typeof reactRouterConfig.prerender === "boolean") {
-    invariant(reactRouterConfig.prerender, "Expected prerender:true");
-    routesToPrerender = determineStaticPrerenderRoutes(
-      routes,
-      viteConfig,
-      true
-    );
-  } else if (typeof reactRouterConfig.prerender === "function") {
-    routesToPrerender = await reactRouterConfig.prerender({
-      getStaticPaths: () =>
-        determineStaticPrerenderRoutes(routes, viteConfig, false),
-    });
-  } else {
-    routesToPrerender = reactRouterConfig.prerender || ["/"];
-  }


This was lifted and is now available on build.prerender

brophdawg11 · 2025-02-06T20:36:35Z

packages/react-router-dev/vite/plugin.ts

-      loader: route.module.loader ? () => null : undefined,
-      action: undefined,
-      handle: route.module.handle,


None of this is needed on the routes, we just need to know id/index/path/children to make our prerender decisions

brophdawg11 · 2025-02-10T16:34:15Z

packages/react-router/lib/dom/ssr/routes.tsx

@@ -347,7 +361,6 @@ export function createClientRoutes(
              "No `routeModule` available for critical-route loader"
            );
            if (!routeModule.clientLoader) {
-              if (isSpaMode) return null;


These are unneccesary because fetchServerLoader already returns null if no loader exists

brophdawg11 · 2025-02-10T16:36:15Z

packages/react-router/lib/server-runtime/server.ts

+    if (
+      !_build.ssr &&
+      _build.prerender.length > 0 &&
+      normalizedPath !== "/" &&


Note to self - ensure we have correct behavior for hard reloads on / in dev mode when it's not prerendered

This reverts commit 8fafeea. No longer needed now that we do export detecton during the virtual route manifest module creation - since that gets invalidated on config change

github-actions · 2025-02-12T16:50:35Z

🤖 Hello there,

We just published version 7.2.0-pre.0 which includes this pull request. If you'd like to take it for a test run please try it out and let us know what you think!

Thanks!

…d-route-typegen * upstream/dev: bump patch to minor for new API: `href` Type-safe href (remix-run#12994) docs: prerender/ssr:false (remix-run#13005) Skip action-only resource routes with prerender:true (remix-run#13004) Update docs for spa/prerendering Improvements to ssr:false + prerender scenarios (remix-run#12948)

github-actions · 2025-02-18T20:28:54Z

🤖 Hello there,

We just published version 7.2.0 which includes this pull request. If you'd like to take it for a test run please try it out and let us know what you think!

Thanks!

per remix-run/react-router#12948 improvements

github-actions · 2025-03-06T21:04:02Z

🤖 Hello there,

We just published version 7.3.0 which includes this pull request. If you'd like to take it for a test run please try it out and let us know what you think!

Thanks!

Add more advanced invalid route export detection for ssr:false + prep…

Loading
Loading status checks…

9a718d3

…render combinations

remix-cla-bot bot added the CLA Signed label Feb 4, 2025

timdorr changed the title ~~Improvements to ssr:false + prerender sceanrios~~ Improvements to ssr:false + prerender scenarios Feb 4, 2025

brophdawg11 added 6 commits February 4, 2025 17:49

Pass build time root loaderData to hydrationData

Loading
Loading status checks…

537ee7d

Add changesets

Loading
Loading status checks…

c7552e6

Enable spa fallback in prerendering

Loading
Loading status checks…

fde52e5

Fix unit test fixtures

b603102

Remove single fetch data strategy from spa mode

aa54c68

Fix integration test and call handleError on prerender 404s

Loading
Loading status checks…

9778c3d

brophdawg11 force-pushed the brophdawg11/spa-prerender branch from 43853ec to 9778c3d Compare February 6, 2025 19:59

brophdawg11 added 2 commits February 6, 2025 15:26

Add integration tests for prerendered spa fallback

Loading
Loading status checks…

697bc5c

Code cleanup

Loading
Loading status checks…

b9cf540

brophdawg11 force-pushed the brophdawg11/spa-prerender branch from 0df6d0c to b9cf540 Compare February 6, 2025 20:37

brophdawg11 commented Feb 6, 2025

View reviewed changes

brophdawg11 added 4 commits February 7, 2025 12:22

Fix bug with navigating from prerender->spa when root route has loader

Loading
Loading status checks…

044f782

handle scenarios where root has a loader in ssr+prerender apps

Loading
Loading status checks…

03c2be7

Docs

Loading
Loading status checks…

902325f

Moar docs

Loading
Loading status checks…

97cf35a

brophdawg11 commented Feb 10, 2025

View reviewed changes

brophdawg11 added 5 commits February 10, 2025 15:17

Updates

Loading
Loading status checks…

735d06d

Invalidate route modules if ssr is flipped to false

8fafeea

Fix e2e test

Loading
Loading status checks…

53da4e8

Fix spa tests

Loading
Loading status checks…

bcc4353

More tests

Loading
Loading status checks…

3e74528

pcattori approved these changes Feb 11, 2025

View reviewed changes

brophdawg11 added 3 commits February 11, 2025 12:15

Add changeset for updated dev server behavior

Loading
Loading status checks…

26ae4ee

Merge branch 'dev' into brophdawg11/spa-prerender

Loading
Loading status checks…

15d90af

Revert "Invalidate route modules if ssr is flipped to false"

Loading
Loading status checks…

9c8a9bf

This reverts commit 8fafeea. No longer needed now that we do export detecton during the virtual route manifest module creation - since that gets invalidated on config change

brophdawg11 force-pushed the brophdawg11/spa-prerender branch from a2f3576 to 9c8a9bf Compare February 11, 2025 19:56

brophdawg11 merged commit abe8008 into dev Feb 11, 2025
8 checks passed

brophdawg11 deleted the brophdawg11/spa-prerender branch February 11, 2025 20:56

brophdawg11 mentioned this pull request Feb 11, 2025

ssr bug in dev when using prerender #12924

Closed

github-actions bot mentioned this pull request Feb 12, 2025

chore: Update version for release (pre) #13011

Merged

brophdawg11 mentioned this pull request Feb 12, 2025

Add prerender SPA mode bug report test #12689

Closed

brophdawg11 mentioned this pull request Feb 12, 2025

SPA Mode should not use Single Fetch revalidation behavior #12740

Closed

brophdawg11 linked an issue Feb 12, 2025 that may be closed by this pull request

SPA Mode should not use Single Fetch revalidation behavior #12740

Closed

brophdawg11 mentioned this pull request Feb 12, 2025

Content of statically generated index page shows up on every dynamic routes #12905

Closed

brophdawg11 mentioned this pull request Feb 13, 2025

ssr: false: build script creates a server bundle and deletes it #12641

Closed

github-actions bot mentioned this pull request Feb 18, 2025

chore: Update version for release #13051

Merged

namoscato added a commit to namoscato/tiny-truths that referenced this pull request Feb 27, 2025

Enable SPA mode

Loading
Loading status checks…

66e87a3

per remix-run/react-router#12948 improvements

namoscato mentioned this pull request Feb 27, 2025

Enable SPA mode namoscato/tiny-truths#4

Merged

brophdawg11 mentioned this pull request Mar 13, 2025

clientLoader revalidate even though shouldRevalidate returns false #12607

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improvements to ssr:false + prerender scenarios #12948

Improvements to ssr:false + prerender scenarios #12948

brophdawg11 commented Feb 4, 2025 •

edited

Loading

changeset-bot bot commented Feb 4, 2025 •

edited

Loading

brophdawg11 Feb 6, 2025

brophdawg11 Feb 6, 2025

brophdawg11 Feb 6, 2025

brophdawg11 Feb 6, 2025

brophdawg11 Feb 6, 2025

brophdawg11 Feb 6, 2025

brophdawg11 Feb 6, 2025

brophdawg11 Feb 6, 2025

brophdawg11 Feb 10, 2025

brophdawg11 Feb 10, 2025

github-actions bot commented Feb 12, 2025

github-actions bot commented Feb 18, 2025

github-actions bot commented Mar 6, 2025

		validatePrerenderedResponse(response, html, "SPA Mode", "/");
		validatePrerenderedHtml(html, "SPA Mode");

Improvements to ssr:false + prerender scenarios #12948

Improvements to ssr:false + prerender scenarios #12948

Conversation

brophdawg11 commented Feb 4, 2025 • edited Loading

changeset-bot bot commented Feb 4, 2025 • edited Loading

🦋 Changeset detected

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Feb 12, 2025

github-actions bot commented Feb 18, 2025

github-actions bot commented Mar 6, 2025

brophdawg11 commented Feb 4, 2025 •

edited

Loading

changeset-bot bot commented Feb 4, 2025 •

edited

Loading