本技能讲解 TanStack Router 与 TanStack Query 的集成方式，即把 TanStack Query 当作外部数据缓存，与 TanStack Router 的 loader 系统配合使用。Router 在其中充当协调者：在导航期间触发数据获取，而 Query 负责缓存、后台重新获取和数据生命周期管理。技能提示，使用前需熟悉 TanStack Router 与 TanStack Query，并先阅读 router-core 和 react-router。
关键配置 技能给出两条 CRITICAL 提示：其一，使用 TanStack Query 时必须设置 defaultPreloadStaleTime: 0，否则 Router 内置的预加载缓存（默认 30s）会使 Query 无法控制数据新鲜度。其二，SSR 场景下应在 createRouter 的工厂函数内部创建 QueryClient，模块级单例会在服务器请求之间泄漏数据。
设置：在 Router 上下文中注入 QueryClient 技能分别给出仅客户端、带上下文的根路由、SSR 安全三种设置方式。仅客户端示例中，在 createRouter 中配置 defaultPreloadStaleTime: 0、context: { queryClient }，并通过 Wrap 包上 QueryClientProvider。根路由使用 createRootRouteWithContext 声明 context 包含 queryClient。SSR 安全版本则在 createAppRouter 函数内每次新建 QueryClient。
SSR 集成 技能提供两种 SSR 方案。其一是使用 @tanstack/react-router-ssr-query 包中的 setupRouterSsrQueryIntegration，可自动完成服务端脱水（dehydrate）与客户端注水（hydrate）、将服务端渲染期间解析的查询流式传输到客户端，并处理查询/变更中抛出的 redirect()，安装命令为 npm install @tanstack/react-router-ssr-query。其二是手动脱水/注水，在 createRouter 中提供 dehydrate 与 hydrate 回调，并在 Wrap 中包裹 QueryClientProvider。
核心模式 推荐模式是在 loader 中使用 ensureQueryData、在组件中使用 useSuspenseQuery：loader 确保渲染前数据已进入缓存（避免加载闪烁），组件订阅缓存以获取更新。技能给出静态查询与带动态参数（$postId）两种示例，其中动态参数通过 params.postId 构造 queryOptions。
流式模式 对于非关键数据，可在 loader 中使用 prefetchQuery 且不 await，使其在 SSR 期间流式传输；关键数据仍用 ensureQueryData 并返回。组件中关键数据用 useSuspenseQuery，非关键数据用 useQuery 并显示加载状态。
错误处理 技能给出配合 useQueryErrorResetBoundary 与 useRouter 的错误组件示例，在 useEffect 中调用 queryErrorResetBoundary.reset()，并通过 router.invalidate() 重试。
常见错误 技能列出四类常见错误：未设置 defaultPreloadStaleTime 为 0（HIGH）；SSR 时在 createRouter 外创建 QueryClient（HIGH）；在 loader 中 await prefetchQuery 阻塞渲染（MEDIUM）；createRootRouteWithContext 缺少双重括号调用（HIGH）。
内置缓存与外部缓存的张力 TanStack Router 自带 SWR 缓存（staleTime、gcTime、defaultPreloadStaleTime）。将 Query 作为外部缓存时，应设置 defaultPreloadStaleTime: 0 防止 Router 缓存短路 Query 的新鲜度逻辑；Router 的 staleTime/gcTime 仍作用于 loader 返回值；纯 Query 模式可从 loader 不返回值，只用 ensureQueryData 产生副作用，并完全从 useSuspenseQuery 读取数据；router.invalidate() 会重跑 loader，但由 Query 依据自身 staleTime 决定是否真正重新获取。
交叉引用 技能引用 router-core/data-loading（内置 loader 缓存基础）与 router-core/ssr（脱水/注水的 SSR 设置）。