tanstack-start

TanStack Start (React) — RC 就绪指南

基于 TanStack Router 的全栈 React，支持按路由配置 SSR/CSR、基于文件的路由、服务端函数，以及一流的 Cloudflare Workers 支持。

适用场景

• 构建需要按路由切换 SSR/CSR/SSG 的全新 React 应用。
• 从 Next.js/React Router 迁移，同时保留基于文件的路由和 API 路由。
• 部署到边缘运行时（Workers），并使用类型化的服务端函数和绑定。
• 需要可预测的路由，以及类型安全的参数/搜索参数和内置预加载。

内容

• 参考资料：快速入门/布局、渲染模式、服务端函数、Cloudflare 托管、执行/身份验证，以及新增的路由/数据/导航/开发工具指南。
• 脚本：scripts/bootstrap-cloudflare-start.sh <app> 用于搭建 Start + Workers + 绑定类型。
• 故障排查：水合、API 路由、绑定、导航/预加载失败。

---

快速入门（React）

npm create @tanstack/start@latest my-app
cd my-app
npm run dev

手动安装（支持所有打包目标）：根据官方安装指南，使用打包器插件（vite、webpack 或 esbuild）添加 @tanstack/react-router 和 @tanstack/react-start。

核心布局提示

• app/routes/** 基于文件的路由 → 路由树、自动代码拆分 + 数据预加载。
• app/entry.client.tsx 对 <StartClient /> 进行水合；app/entry.server.tsx 用 createServerEntry 封装。
• app/config.ts 或 app/start.ts 用于设置 defaultSsr、spaMode、中间件和上下文。

---

路由 + 数据最佳实践

• 类型安全的参数和搜索参数：createFileRoute() 会推断路径参数；添加 validateSearch（zod）以解析和转换搜索参数。
• 路由匹配顺序是确定的（index → static → dynamic → splat）；添加兜底路由时可依赖此顺序。
• 加载器在每次位置变更时运行一次；返回普通数据，并通过抛出 redirect()/notFound() 进行控制流处理。
• 数据变更：将 action/服务端函数放在一起；保持加载器只读，并在变更后通过 router.invalidate() 使数据失效。
• TanStack Query 桥接：在路由器上下文中创建 QueryClient，并在加载器中使用 ensureQueryData 以消除重复请求。
• 延迟/外部数据：流式传输部分数据，或从外部加载器读取；优先使用兼容 suspense 的响应。
• Head 管理：为每个路由设置 head，用于 <title>/meta；根据加载器数据生成内容，以保持 SEO 一致。
• 未找到/身份验证：在加载器/中间件中抛出 notFound() 或 redirect()；使用错误边界改善用户体验。

路由示例（类型化搜索参数 + 仅数据 SSR）：

// app/routes/posts.$postId.tsx
import { createFileRoute, redirect } from '@tanstack/react-router'
import { z } from 'zod'

export const Route = createFileRoute('/posts/$postId')({
  validateSearch: z.object({ preview: z.boolean().optional() }),
  ssr: 'data-only',
  loader: async ({ params, search, context }) => {
    const post = await context.queryClient.ensureQueryData(['post', params.postId], () =>
      fetch(`/api/posts/${params.postId}?preview=${!!search.preview}`).then(r => r.json())
    )
    if (!post.published && !search.preview) throw redirect({ to: '/drafts' })
    return { post }
  },
})

---

导航、预加载与用户体验

• Link 预取默认值：<Link preload="intent">（悬停/聚焦）会预加载路由数据/代码；对于首屏路由，使用 preload="render"。
• 编程式预加载：使用 router.preloadRoute({ to, search }) 在导航前预热缓存（例如，在元素可见时）。
• 路由遮罩：保留规范 URL，同时显示便于用户阅读的遮罩（例如，将 /products?slug=abc 遮罩为 /p/abc）。
• 导航阻止：使用 router.navigate({ to, replace, from }) 的阻止器或 useBlocker，保护未保存的表单。
• 滚动恢复：启用 scrollRestoration，以便在前进/后退时恢复位置；使用长列表时可按路由自定义。
• 搜索参数序列化：自定义解析/字符串化逻辑，以保持数字/日期稳定，并避免布尔值被字符串化。

---

渲染与性能

• 按路由 SSR：在路由上设置 ssr: true | false | 'data-only'；defaultSsr 配置用于设置默认值。
• 代码拆分：基于文件的路由会自动拆分；对于基于代码的路由，可添加 lazy/load 以手动拆分代码块。
• 预加载策略：将 preload="intent" 链接与 defaultPreloadStaleTime 搭配使用，以避免过度请求。
• 渲染优化：保持加载器纯净，对重量级组件进行记忆化，并在 CSR 路由中使用 pendingComponent 以避免布局偏移。

---

开发工具、Lint 和 LLM 支持

• 在开发期间添加 <RouterDevtools />，以检查匹配项、loader 状态和预加载情况。
• 启用 ESLint 插件 @tanstack/eslint-plugin-router 并使用推荐配置，以强制执行对类型推断敏感的属性顺序（例如，beforeLoad 要放在 loader 前面）。
• 面向 LLM 的路由：Router 会向 LLM Agent 暴露结构化路由元数据；在 Route 元数据中保持描述简洁，以便 AI 更好地导航。

---

部署说明（适用于 Cloudflare）

• 将 cloudflare({ viteEnvironment: { name: 'ssr' } }) 放在 Vite 插件列表首位，以便将绑定传递到服务器入口。
• 更改后重新生成绑定：npm run cf-typegen。
• 对于静态内容较多的网站，启用预渲染，将 HTML 部署到 Workers Assets/Pages；排除参数路由或添加显式的 pages。

---

发布检查清单

• 路由加载时没有 hydration 警告（对于非确定性 UI，优先使用 ssr: 'data-only'）。
• 使用 validateSearch 验证搜索参数，并在需要时使用自定义序列化器。
• 为高流量路由配置链接预加载；为未保存的表单添加阻止器。
• 已启用 ESLint 插件（create-route-property-order 规则），且 npm run check 通过。
• 已在本地验证开发工具；router.matches 状态看起来正确。
• Cloudflare 绑定已添加类型（cf-typegen），并已通过 curl -N 测试流式传输。