TanStackStart v0
自动
框架
版本
菜单
入门
示例
教程

选择性服务器端渲染 (SSR)

什么是选择性 SSR？

在 TanStack Start 中，匹配初始请求的路由默认在服务器上渲染。这意味着 beforeLoad 和 loader 在服务器上执行，然后渲染路由组件。生成的 HTML 发送到客户端，客户端将标记水合为完全交互式的应用程序。

但是，在某些情况下，您可能希望为某些路由或所有路由禁用 SSR，例如：

  • 当 beforeLoad 或 loader 需要仅浏览器 API（例如 localStorage）时。
  • 当路由组件依赖于仅浏览器 API（例如 canvas）时。

TanStack Start 的选择性 SSR 功能让您可以配置：

  • 哪些路由应该在服务器上执行 beforeLoad 或 loader。
  • 哪些路由组件应该在服务器上渲染。

这与 SPA 模式相比如何？

TanStack Start 的 SPA 模式完全禁用 beforeLoad 和 loader 的服务器端执行，以及路由组件的服务器端渲染。选择性 SSR 允许您在每个路由的基础上配置服务器端处理，无论是静态还是动态。

配置

您可以使用 ssr 属性控制路由在初始服务器请求期间的处理方式。如果未设置此属性，则默认为 true。您可以使用 createRouter 中的 defaultSsr 选项更改此默认值：

tsx
// src/router.tsx
import { createRouter as createTanStackRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

export function createRouter() {
  const router = createTanStackRouter({
    routeTree,
    scrollRestoration: true,
    defaultPendingComponent: () => <div>Loading...</div>,
    // Disable SSR by default
    defaultSsr: false,
  })

  return router
}

// src/router.tsx
import { createRouter as createTanStackRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

export function createRouter() {
  const router = createTanStackRouter({
    routeTree,
    scrollRestoration: true,
    defaultPendingComponent: () => <div>Loading...</div>,
    // Disable SSR by default
    defaultSsr: false,
  })

  return router
}

ssr: true

除非另有配置，否则这是默认行为。在初始请求时，它将：

  • 在服务器上运行 beforeLoad 并将结果上下文发送到客户端。
  • 在服务器上运行 loader 并将加载器数据发送到客户端。
  • 在服务器上渲染组件并将 HTML 标记发送到客户端。
tsx
// src/routes/posts/$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
  ssr: true,
  beforeLoad: () => {
    console.log('Executes on the server during the initial request')
    console.log('Executes on the client for subsequent navigation')
  },
  loader: () => {
    console.log('Executes on the server during the initial request')
    console.log('Executes on the client for subsequent navigation')
  },
  component: () => <div>This component is rendered on the server</div>,
})

// src/routes/posts/$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
  ssr: true,
  beforeLoad: () => {
    console.log('Executes on the server during the initial request')
    console.log('Executes on the client for subsequent navigation')
  },
  loader: () => {
    console.log('Executes on the server during the initial request')
    console.log('Executes on the client for subsequent navigation')
  },
  component: () => <div>This component is rendered on the server</div>,
})

ssr: false

这会禁用服务器端：

  • 执行路由的 beforeLoad 和 loader。
  • 渲染路由组件。
tsx
// src/routes/posts/$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
  ssr: false,
  beforeLoad: () => {
    console.log('Executes on the client during hydration')
  },
  loader: () => {
    console.log('Executes on the client during hydration')
  },
  component: () => <div>This component is rendered on the client</div>,
})

// src/routes/posts/$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
  ssr: false,
  beforeLoad: () => {
    console.log('Executes on the client during hydration')
  },
  loader: () => {
    console.log('Executes on the client during hydration')
  },
  component: () => <div>This component is rendered on the client</div>,
})

ssr: 'data-only'

这个混合选项将：

  • 在服务器上运行 beforeLoad 并将结果上下文发送到客户端。
  • 在服务器上运行 loader 并将加载器数据发送到客户端。
  • 禁用路由组件的服务器端渲染。
tsx
// src/routes/posts/$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
  ssr: 'data-only',
  beforeLoad: () => {
    console.log('Executes on the server during the initial request')
    console.log('Executes on the client for subsequent navigation')
  },
  loader: () => {
    console.log('Executes on the server during the initial request')
    console.log('Executes on the client for subsequent navigation')
  },
  component: () => <div>This component is rendered on the client</div>,
})

// src/routes/posts/$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
  ssr: 'data-only',
  beforeLoad: () => {
    console.log('Executes on the server during the initial request')
    console.log('Executes on the client for subsequent navigation')
  },
  loader: () => {
    console.log('Executes on the server during the initial request')
    console.log('Executes on the client for subsequent navigation')
  },
  component: () => <div>This component is rendered on the client</div>,
})

函数形式

为了更大的灵活性，您可以使用 ssr 属性的函数形式在运行时决定是否对路由进行 SSR：

tsx
// src/routes/docs/$docType/$docId.tsx
export const Route = createFileRoute('/docs/$docType/$docId')({
  validateSearch: z.object({ details: z.boolean().optional() }),
  ssr: ({ params, search }) => {
    if (params.status === 'success' && params.value.docType === 'sheet') {
      return false
    }
    if (search.status === 'success' && search.value.details) {
      return 'data-only'
    }
  },
  beforeLoad: () => {
    console.log('Executes on the server depending on the result of ssr()')
  },
  loader: () => {
    console.log('Executes on the server depending on the result of ssr()')
  },
  component: () => <div>This component is rendered on the client</div>,
})

// src/routes/docs/$docType/$docId.tsx
export const Route = createFileRoute('/docs/$docType/$docId')({
  validateSearch: z.object({ details: z.boolean().optional() }),
  ssr: ({ params, search }) => {
    if (params.status === 'success' && params.value.docType === 'sheet') {
      return false
    }
    if (search.status === 'success' && search.value.details) {
      return 'data-only'
    }
  },
  beforeLoad: () => {
    console.log('Executes on the server depending on the result of ssr()')
  },
  loader: () => {
    console.log('Executes on the server depending on the result of ssr()')
  },
  component: () => <div>This component is rendered on the client</div>,
})

ssr 函数仅在初始请求期间在服务器上运行，并从客户端包中剥离。

search 和 params 在验证后作为判别联合传入：

tsx
params:
    | { status: 'success'; value: Expand<ResolveAllParamsFromParent<TParentRoute, TParams>> }
    | { status: 'error'; error: unknown }
search:
    | { status: 'success'; value: Expand<ResolveFullSearchSchema<TParentRoute, TSearchValidator>> }
    | { status: 'error'; error: unknown }

params:
    | { status: 'success'; value: Expand<ResolveAllParamsFromParent<TParentRoute, TParams>> }
    | { status: 'error'; error: unknown }
search:
    | { status: 'success'; value: Expand<ResolveFullSearchSchema<TParentRoute, TSearchValidator>> }
    | { status: 'error'; error: unknown }

如果验证失败，status 将为 error，error 将包含失败详细信息。否则，status 将为 success，value 将包含验证的数据。

继承

在运行时，子路由继承其父路由的选择性 SSR 配置。但是，继承的值只能更改为更严格的值（即 true 到 data-only 或 false，以及 data-only 到 false）。例如：

tsx
root { ssr: undefined }
  posts { ssr: false }
     $postId { ssr: true }

root { ssr: undefined }
  posts { ssr: false }
     $postId { ssr: true }
  • root 默认为 ssr: true。
  • posts 明确设置 ssr: false，因此 beforeLoad 和 loader 都不会在服务器上运行，路由组件也不会在服务器上渲染。
  • $postId 设置 ssr: true，但从其父路由继承 ssr: false。因为继承的值只能更改为更严格的值，所以 ssr: true 没有效果，继承的 ssr: false 将保持不变。

另一个例子：

tsx
root { ssr: undefined }
  posts { ssr: 'data-only' }
     $postId { ssr: true }
       details { ssr: false }

root { ssr: undefined }
  posts { ssr: 'data-only' }
     $postId { ssr: true }
       details { ssr: false }
  • root 默认为 ssr: true。
  • posts 设置 ssr: 'data-only'，因此 beforeLoad 和 loader 在服务器上运行，但路由组件不在服务器上渲染。
  • $postId 设置 ssr: true，但从其父路由继承 ssr: 'data-only'。
  • details 设置 ssr: false，因此 beforeLoad 和 loader 都不会在服务器上运行，路由组件也不会在服务器上渲染。这里继承的值被更改为更严格的值，因此 ssr: false 将覆盖继承的值。

回退渲染

对于第一个具有 ssr: false 或 ssr: 'data-only' 的路由，服务器将渲染路由的 pendingComponent 作为回退。如果未配置 pendingComponent，将渲染 defaultPendingComponent。如果两者都未配置，则不会渲染回退。

在客户端水合期间，即使路由没有定义 beforeLoad 或 loader，此回退也将至少显示 minPendingMs（如果未配置则为 defaultPendingMinMs）。

在 GitHub 上编辑
服务器路由
SPA 模式