在 React SPA 中用 TanStack…

当需要为 React SPA 提供类型安全文件式路由、路由级数据加载、TanStack Query 集成，并可能部署到 Cloudflare Workers 时使用。

适用场景

解决思路

1. 安装运行时依赖：`bun add @tanstack/react-router @tanstack/router-devtools`。
2. 安装开发依赖：`bun add -d @tanstack/router-plugin`。
3. 使用已验证版本：`@tanstack/react-router` v1.170.18（验证日期 2026-08-03）。
4. 配置 `vite.config.ts`：引入 `defineConfig`、`react`、以及来自 `@tanstack/router-plugin/vite` 的 `TanStackRouterVite`。
5. 在 `vite.config.ts` 的 `plugins` 数组中按顺序加入 `TanStackRouterVite()` 和 `react()`，且 `TanStackRouterVite()` 必须放在 `react()` 之前。
6. 创建根路由 `src/routes/__root.tsx`：使用 `createRootRoute`，在组件中渲染导航链接 `<Link to='/'>Home</Link>`、`<Link to='/about'>About</Link>`、分隔线 `<hr />` 和 `<Outlet />`。
7. 创建首页路由 `src/routes/index.tsx`：使用 `createFileRoute('/')({ component: () => <h1>Home Page</h1> })`。
8. 创建关于页路由 `src/routes/about.tsx`：使用 `createFileRoute('/about')({ component: () => <h1>About Page</h1> })`。
9. 在 `src/main.tsx` 中从自动生成文件 `./routeTree.gen` 引入 `routeTree`。
10. 在 `src/main.tsx` 中用 `createRouter({ routeTree })` 创建 router，并用 `<RouterProvider router={router} />` 挂载应用。
11. 使用类型安全导航：`<Link to='/posts/$postId' params={{ postId: '123' }} />`；若 `to` 指向不存在的路由，TypeScript 会报错。
12. 用路由 loader 做数据获取：在 `src/routes/posts.$postId.tsx` 中用 `createFileRoute('/posts/$postId')` 配置 `loader: async ({ params }) => { const post = await fetchPost(params.postId); return { post } }`。
13. 在 loader 对应组件中通过 `component: ({ useLoaderData }) => { const { post } = useLoaderData(); return <h1>{post.title}</h1> }` 读取 loader 返回数据。
14. 集成 TanStack Query：用 `queryOptions({ queryKey: ['posts', postId], queryFn: () => fetchPost(postId) })` 定义查询选项。
15. 在路由 loader 中通过 `context: { queryClient }` 调用 `queryClient.ensureQueryData(postQueryOptions(params.postId))` 预取数据。
16. 在组件中用 `Route.useParams()` 获取 `postId`，并用 `useQuery(postQueryOptions(postId))` 读取 `data: post`。
17. 修复 devtools 依赖解析错误：若构建报 `@tanstack/router-devtools-core` 找不到，执行 `bun add @tanstack/router-devtools`。
18. 修复路由未自动生成问题：确认 `TanStackRouterVite()` 位于 `react()` 之前。
19. 修复 `Link to` 没有类型问题：在 `main.tsx` 中引入 `./routeTree.gen` 的 `routeTree` 以注册类型。
20. 修复 loader 不运行问题：确保路由文件导出 `Route`，例如 `export const Route = createFileRoute('/path')({ loader: ... })`。
21. 处理 TanStack Form 与 Router 的内存泄漏：这是已知问题 #5734，临时改用 React Hook Form，或等待修复。
22. 部署到 Cloudflare Workers 时，在 Vite 配置中引入来自 `@cloudflare/vite-plugin` 的 `cloudflare`，并加入 `TanStackRouterVite()`、`react()`、`cloudflare()`。
23. 创建 Cloudflare Workers API：在 `functions/api/posts.ts` 中导出 `onRequestGet({ env })`，用 `env.DB.prepare('SELECT * FROM posts').all()` 查询，并 `return Response.json(results)`。
24. 客户端路由通过 loader 调用 API：`const posts = await fetch('/api/posts').then(r => r.json())`，返回 `{ posts }`。
25. 使用模板加速：查看 `~/.claude/skills/tanstack-router/templates/` 下的 `package.json`、`vite.config.ts`、`basic-routes/`、`route-with-loader.tsx`、`query-integration.tsx`、`nested-routes/`、`cloudflare-deployment.md`。
26. 查阅参考文档：查看 `~/.claude/skills/tanstack-router/references/` 下的 `file-based-routing.md`、`type-safety.md`、`data-loading.md`、`cloudflare-workers.md`、`common-errors.md`、`migration-guide.md`。
27. 与现有技能集成：可配合 `tanstack-query` 做数据获取、`tanstack-table` 展示数据、`cloudflare-worker-base` 做 API 后端、`tailwind-v4-shadcn` 做 UI 样式。
28. 若从 React Router 迁移，参考 `migration-guide.md`。
29. 若需要嵌套布局路由，参考 `nested-routes/` 模板。
30. 在兼容栈上验证：React 19.2、Vite 7.3、TypeScript 5.9、Cloudflare Workers（Wrangler 4.0）、TanStack Query v5.101.4、`@tanstack/react-router` v1.170.18；确认支持 Cloudflare Workers + Static Assets、TanStack Query 集成、TypeScript strict mode。

适用边界 · 注意事项

• 项目不使用 React/TanStack Router，或不需要类型安全/文件式路由、路由 loader、TanStack Query 集成时，本技能不适用。
• 不使用 Vite，或不能/不想通过 `@tanstack/router-plugin` 自动生成 `routeTree.gen.ts` 时，本技能的 Vite 配置与自动路由生成做法不适用。
• 需要将 TanStack Form 与 Router 组合时不适用：存在已知内存泄漏问题 #5734，应改用 React Hook Form 或等待修复。