tanstack-start

TanStack Start

当工作涉及 TanStack Start 或 @tanstack/react-start 时，使用此技能。

工作流

1. 修改代码前，先确认应用当前的 Start 结构：
   • @tanstack/react-start、@tanstack/react-router、构建插件、React，以及可选的 @tanstack/react-query 的软件包版本。
   • 构建工具：Vite 或 Rsbuild。
   • Start 入口文件：src/router.tsx、src/routes/__root.tsx、生成的 routeTree.gen.ts、可选的 src/start.ts，以及可选的自定义 src/server.ts。
   • src/routes 下的路由文件，尤其是 loader、server.handlers、中间件和身份验证边界。
2. 如果任务依赖最新行为、部署适配器、安全默认设置、RC/实验性 API 或版本不匹配，请刷新当前文档。先查看 source-map.md。
3. 新建应用或处理路由/设置工作时，使用 setup-routing.md。
4. 在 src/routes 下添加、移动或审查页面/布局 UI、钩子或辅助工具时，请遵循 route-colocation.md。每个页面优先使用文件夹 + index.tsx；将仅供路由使用的 UI 放在 -components / -hooks / -lib 中；将可复用的功能代码放在 src/modules/<feature>/ 中。
5. 处理数据加载、服务端函数、服务端路由、中间件、环境边界、身份验证和执行模型问题时，使用 server-data.md。
6. 处理部署、生产模式、预渲染、ISR、SPA 模式、选择性 SSR、自定义服务端入口和验证时，使用 deployment-production.md。

实现判断

• 将 TanStack Start 视为由 TanStack Router 驱动的全栈 React 框架。以 Router 约定为核心：类型化文件路由、路由 loader、路由上下文、搜索参数和路由失效。
• 每个页面路由优先使用文件夹 + index.tsx（需要同目录组织时，避免使用扁平页面叶节点）。将仅供路由使用的模块放在连字符前缀文件夹中（-components、-hooks、-lib 等）。将可复用的功能代码放在 src/modules/<feature>/ 中（复用测试）。切勿在 src/routes 下添加无前缀的非路由文件——它们会成为 URL。详情见：route-colocation.md。
• 截至 2026-10-01，TanStack Start 仍处于 Release Candidate 阶段：功能已完备，API 被认为稳定，但在 v1 发布前仍可能存在缺陷。npm latest 是当前推荐的版本线。React Server Components 仍处于实验阶段。依赖不稳定或近期变更的行为前，请先确认最新文档。
• 同源应用 RPC 使用服务端函数。公共或外部 HTTP 端点、webhook、表单提交以及 API 风格的 Response 处理使用服务端路由。
• 不要依赖路由守卫作为数据安全边界。对每个访问私有数据的服务端函数和服务端路由都进行授权。
• 使用 TanStack Query 时，在 getRouter() 内创建 QueryClient（绝不要放在模块作用域），接入 setupRouterSsrQueryIntegration，在 loader 和组件间共享 queryOptions，并使用 queryClient.query 等待关键数据（Query 5.102+；ensureQueryData 已弃用）。
• 请记住，路由 loader 具有同构性。将机密信息和仅限服务端的工作放在服务端函数、服务端路由、仅限服务端的工具或 .server.* 模块后面。
• 如果应用定义了 src/start.ts，请明确保留或安装服务端函数的 CSRF 中间件。
• 在边缘运行时，按请求读取服务端环境变量。仅对有意向客户端公开的值使用公共前缀。
• 保持生成的路由树文件由生成器管理；除非仓库明确采用生成快照工作流，否则不要手动编辑。

验证

优先使用代码库现有的检查。对于有实质性影响的 Start 更改，至少包括以下相关检查：

• 类型检查／构建，确保路由树生成正常运行。
• 针对加载器、服务端函数、服务端路由和中间件的单元或集成测试。
• 浏览器冒烟测试，检查导航、水合、重定向、待处理／错误状态和表单。
• 更改托管方式、环境变量、SSR 模式、预渲染或服务端入口点时，进行部署或适配器冒烟测试。
• 发布时，按照 deployment-production.md 中的生产检查清单进行检查：扫描机密泄漏、直接端点授权、双账号缓存隔离、状态码和回滚。