单页应用 (SPA)

本指南重点介绍如何使用 React Router 框架模式构建单页应用程序。如果您在声明式或数据模式下使用 React Router，您可以设计自己的 SPA 架构。

当使用 React Router 作为框架时，您可以通过在 react-router.config.ts 文件中设置 ssr:false 来启用“SPA 模式”。这将禁用运行时服务器端渲染，并在构建时生成一个 index.html，您可以将其作为 SPA 提供和激活。

典型的单页应用程序会发送一个几乎空白的 index.html 模板，其中只包含一个空的 <div id="root"></div>。相比之下，react-router build（在 SPA 模式下）会在构建时将您的根路由预渲染到一个 index.html 文件中。这意味着您可以：

发送超过一个空的 <div>
使用根 loader 为您的应用程序外壳加载数据
使用 React 组件生成用户看到的初始页面（根 HydrateFallback）
稍后重新启用服务器渲染，而无需更改任何有关 UI 的内容

SPA 模式是“预渲染”的一种特殊形式，允许您从同一个 HTML 文件为应用程序中的所有路径提供服务。如果您想进行更广泛的预渲染，请参考预渲染指南。

1. 禁用运行时服务器渲染

服务器渲染默认是启用的。在 react-router.config.ts 中将 ssr 标志设置为 false 来禁用它。

import { type Config } from "@react-router/dev/config";

export default {
  ssr: false,
} satisfies Config;

将其设置为 false 后，将不再生成服务器构建。

需要注意的是，设置 ssr:false 只会禁用运行时服务器渲染。React Router 仍然会在构建时对您的根路由进行服务器渲染，以生成 index.html 文件。这就是为什么您的项目仍然需要依赖 @react-router/node，并且您的路由需要是 SSR 安全的。这意味着即使禁用了服务器渲染，您在初始渲染期间也不能调用 window 或其他仅限浏览器的 API。

2. 为根路由添加一个 `HydrateFallback` 和可选的 `loader`

SPA 模式将在构建时生成一个 index.html 文件，您可以将其作为 SPA 的入口点。这只会渲染根路由，以便它能够在运行时为您的应用程序中的任何路径进行激活。

为了提供比一个空 <div> 更好的加载 UI，您可以向根路由添加一个 HydrateFallback 组件，以便在构建时将您的加载 UI 渲染到 index.html 中。这样，在 SPA 加载/激活时，它会立即显示给用户。

import LoadingScreen from "./components/loading-screen";

export function Layout() {
  return <html>{/*...*/}</html>;
}

export function HydrateFallback() {
  return <LoadingScreen />;
}

export default function App() {
  return <Outlet />;
}

因为根路由是在构建时进行服务器渲染的，所以如果您愿意，也可以在根路由中使用 loader。这个 loader 将在构建时被调用，数据将通过可选的 HydrateFallback loaderData 属性提供。

import { Route } from "./+types/root";

export async function loader() {
  return {
    version: await getVersion(),
  };
}

export function HydrateFallback({
  loaderData,
}: Route.ComponentProps) {
  return (
    <div>
      <h1>Loading version {loaderData.version}...</h1>
      <AwesomeSpinner />
    </div>
  );
}

在使用 SPA 模式时，您不能在应用程序的任何其他路由中包含 loader，除非您正在预渲染这些页面。

3. 使用客户端加载器和客户端操作

在禁用服务器渲染后，您仍然可以使用 clientLoader 和 clientAction 来管理路由数据和突变。

import { Route } from "./+types/some-route";

export async function clientLoader({
  params,
}: Route.ClientLoaderArgs) {
  let data = await fetch(`/some/api/stuff/${params.id}`);
  return data;
}

export async function clientAction({
  request,
}: Route.ClientActionArgs) {
  let formData = await request.formData();
  return await processPayment(formData);
}

4. 将所有 URL 指向 index.html

运行 react-router build 后，将 build/client 目录部署到您喜欢的任何静态主机。

与部署任何 SPA 一样，您需要配置您的主机，将所有 URL 指向客户端构建的 index.html。一些主机默认会这样做，但其他主机则不会。例如，主机可能支持一个 _redirects 文件来执行此操作。

/*    /index.html   200

如果您在应用程序的有效路由上遇到 404 错误，很可能是因为您需要配置您的主机。

单页应用 (SPA)

1. 禁用运行时服务器渲染

2. 为根路由添加一个 HydrateFallback 和可选的 loader

3. 使用客户端加载器和客户端操作

4. 将所有 URL 指向 index.html

2. 为根路由添加一个 `HydrateFallback` 和可选的 `loader`