Update docs for spa/prerendering

Author: brophdawg11

docs/how-to/pre-rendering.md

@@ -6,9 +6,9 @@ title: Pre-Rendering
 
 Pre-rendering allows you to render pages at build time instead of on a runtime server to speed up page loads for static content.
 
-In some cases, you'll serve these pages _alongside_ a runtime SSR server. If you wish to pre-render pages and deploy them _without_ a runtime SSR server, please see the [Pre-rendering with `ssr:false`](#Pre-rendering-with-ssrfalse) section below.
+In some cases, you'll serve these pages _alongside_ a runtime SSR server. If you wish to pre-render pages and deploy them _without_ a runtime SSR server, please see the [Pre-rendering with `ssr:false`](#pre-rendering-without-a-runtime-ssr-server) section below.
 
-## Pre-rendering with ssr:true
+## Pre-rendering alongside a runtime SSR server
 
 ### Configuration
 
@@ -82,7 +82,7 @@ Prerender: Generated build/client/blog/my-first-post/index.html
 
 During development, pre-rendering doesn't save the rendered results to the public directory, this only happens for `react-router build`.
 
-## Pre-rendering with `ssr:false`
+## Pre-rendering without a runtime SSR server
 
 The above examples assume you are deploying a runtime server, but are pre-rendering some static pages in order to serve them faster and avoid hitting the server.
 
@@ -99,7 +99,7 @@ export default {
 
 If you specify `ssr:false` without a `prerender` config, React Router refers to that as [SPA Mode](./spa). In SPA Mode, we render a single HTML file that is capable of hydrating for _any_ of your application paths. It can do this because it only renders the `root` route into the HTML file and then determines which child routes to load based on the browser URL during hydration. This means you can use a `loader` on the root route, but not on any other routes because we don't know which routes to load until hydration in the browser.
 
-If you want to pre-render paths with `ssr:false`, those matched routes _can_ have loaders because we'll pre-render all of the matched routes for those paths, not just the root. Usually, with `prerender:true`, you'll be pre-rendering all of your application routes into a full SSG setup.
+If you want to pre-render paths with `ssr:false`, those matched routes _can_ have loaders because we'll pre-render all of the matched routes for those paths, not just the root. You cannot include `actions` or `headers` functions in any routes when `ssr:false` is set because there will be no runtime server to run them on.
 
 ### Pre-rendering with a SPA Fallback
 
@@ -126,10 +126,12 @@ export default {
 } satisfies Config;
 ```
 
-You can configure your deployment server to serve this file for any path that otherwise would 404.
-
-Here's an example of how you can do this with the [`sirv-cli`](https://www.npmjs.com/package/sirv-cli#user-content-single-page-applications) tool:
+You can configure your deployment server to serve this file for any path that otherwise would 404. Here's an example of how you can do this with the [`sirv-cli`](https://www.npmjs.com/package/sirv-cli#user-content-single-page-applications) tool:
 
 ```sh
+# If you did not pre-render the `/` route
+sirv-cli build/client --single index.html
+
+# If you pre-rendered the `/` route
 sirv-cli build/client --single __spa-fallback.html
 ```

docs/how-to/spa.md

@@ -23,7 +23,33 @@ export default {
 
 With this set to false, the server build will no longer be generated.
 
-## 2. Use client loaders and client actions
+## 2. Add a `HydrateFallback` to your root route
+
+SPA Mode will generate an `index.html` file at build-time that you can serve as the entry point for your SPA. This will only render the root route so that it is capable of hydrating at runtime for any path in your application.
+
+To provide a better/faster loading UI, you can add a `HydrateFallback` component to your root route to render your loading UI into the `index.html` at build time. This way, it will be shown to users immediately while the SPA is loading/hydrating.
+
+```tsx filename=root.tsx
+import { Route } from "./+types/root";
+import AwesomeSpinner from "./components/spinner";
+
+export function Layout() {
+  return <html>{/*...*/}</html>;
+}
+
+// Server-rendered at build time into `index.html` (inside `<Layout>`)
+export function HydrateFallback() {
+  return <AwesomeSpinner />;
+}
+
+export default function App() {
+  return <Outlet />;
+}
+```
+
+Because the root route is server-rendered at build time, you can also use a `loader` in your root route if you choose, and access the data via the optional `HydrateFallback` `loaderData` prop. You cannot in include a loader in any other routes in your app when using SPA Mode.
+
+## 3. Use client loaders and client actions
 
 With server rendering disabled, you can still use `clientLoader` and `clientAction` to manage route data and mutations.
 
@@ -45,11 +71,11 @@ export async function clientAction({
 }
 ```
 
-## 3. Pre-rendering
+## 4. Pre-rendering
 
 Pre-rendering can be configured for paths with static data known at build time for faster initial page loads. Refer to [Pre-rendering](./pre-rendering) to set it up.
 
-## 4. Direct all URLs to index.html
+## 5. Direct all URLs to index.html
 
 After running `react-router build`, deploy the `build/client` directory to whatever static host you prefer.
 

integration/vite-prerender-test.ts

@@ -745,7 +745,8 @@ test.describe("Prerendering", () => {
       let stderr = result.stderr.toString("utf8");
       expect(stderr).toMatch(
         "Prerender: 2 invalid route export(s) in `routes/a` when prerendering " +
-          "with `ssr:false`: headers, action.  See https://reactrouter.com/how-to/spa for more information."
+          "with `ssr:false`: headers, action.  " +
+          "See https://reactrouter.com/how-to/pre-rendering for more information."
       );
     });
 
@@ -773,8 +774,8 @@ test.describe("Prerendering", () => {
       expect(stderr).toMatch(
         "Prerender: 1 invalid route export in `routes/b` when using `ssr:false` " +
           "with `prerender` because the route is never prerendered so the loader " +
-          "will never be called.  See https://reactrouter.com/how-to/spa for more " +
-          "information."
+          "will never be called.  See https://reactrouter.com/how-to/pre-rendering " +
+          "for more information."
       );
     });
 

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

@@ -2643,7 +2643,7 @@ async function validateSsrFalsePrerenderExports(
         `Prerender: ${invalidApis.length} invalid route export(s) in ` +
           `\`${route.id}\` when prerendering with \`ssr:false\`: ` +
           `${invalidApis.join(", ")}.  ` +
-          "See https://reactrouter.com/how-to/spa for more information."
+          "See https://reactrouter.com/how-to/pre-rendering for more information."
       );
     }
 
@@ -2653,7 +2653,7 @@ async function validateSsrFalsePrerenderExports(
         `Prerender: 1 invalid route export in \`${route.id}\` when ` +
           "using `ssr:false` with `prerender` because the route is never " +
           "prerendered so the loader will never be called.  " +
-          "See https://reactrouter.com/how-to/spa for more information."
+          "See https://reactrouter.com/how-to/pre-rendering for more information."
       );
     }
   }