SuperAPI AI 工具集

start-routing-data

数据与分析

查看项目

更新于 10-15 21:48

技能介绍

用途:该技能聚焦 TanStack Start 特有的路由数据加载,涵盖同构 loader、在 loader 中使用 TanStack Query 预取、按路由选择性 SSR,以及 mutation 后刷新数据。通用的 TanStack Router/Query(路由树、文件式路由、搜索参数校验、useQuery/useMutation 基础、缓存配置)不在此范围。

主要能力:

  1. 同构 loader:Route.loader 在首次请求时于服务端运行,导航时于客户端运行,因此 loader 顶层不得访问 window/localStorage,需用 ssr: false/'data-only' 或 useEffect 规避。
  2. loader 中查询:用 context.queryClient.ensureQueryData(queryOptions) 在服务端预取,组件用 useQuery 读取缓存;queryOptions 工厂应共享以保证缓存键一致。
  3. 选择性 SSR:按路由设置 ssr: true | false | 'data-only';ssr 会向下继承且只能收紧,子路由无法把父级的 ssr: false 改回 true。
  4. 写入与失效:通过 server function 写入后,用 router.invalidate() 刷新 loader 数据,或用 queryClient.invalidateQueries 刷新 Query 缓存。

使用方式:

  • 在 router.tsx 中 createRouter({ context: { queryClient } }),loader 通过 context.queryClient 预取,不要新建 client。
  • 将 queryOptions 工厂放在 src/queries/,同时传给 ensureQueryData 与 useQuery。
  • loader 直接返回 ensureQueryData 的 promise(Start 会 await)。
  • 组件需要 window 但数据仍需 SSR 时用 ssr: 'data-only'。

推荐目录结构:src/router.tsx、src/routes/posts.$postId.tsx(loader: ensureQueryData + component: useQuery)、src/queries/posts.ts。

最佳实践:复用 queryOptions 工厂;避免 loader 与组件重复 query key(破坏水合去重);避免在 loader 顶层读取 localStorage/window;避免在 loader 已填充缓存时再用 useEffect 重新请求。

限制:仅覆盖 Start 特有部分,通用 Router/Query API 问题应参考其他技能。具体安装命令、版本要求、配置细节及完整代码模板资料未提供。