tanstack-integration-best-practices

此技能为使用 TanStack 生态系统构建全端应用程序的开发人员提供了结构化的指南。它专注于 TanStack Query（状态管理）、TanStack Router（路由与数据加载）与 TanStack Start（SSR 与全端能力）之间的关键集成点。主要目标是消除这些强大函式库在独立使用时常见的问题，例如 hydration 不匹配、数据瀑布流以及不一致的缓存策略。通过遵循这些规则，开发人员可以建立稳固、类型安全的架构，以极小的阻力处理从服务器到客户端的复杂数据需求。此技能非常适合软件工程师、全端开发人员以及被指派配置现代化 React 应用程序的 AI 代码助理。无论是迁移现有项目还是构建新的高性能网页应用程序，这些集成模式都有助于保持良好的关注点分离，同时发挥每个 TanStack 函式库的特定优势。

• 通过协调加载器 (Loaders) 与查询缓存机制，编排有效的数据获取模式。

• 通过共享上下文与路由集成的数据提供者，确保全端的类型安全。

• 提供统一的配置模式，以优化服务器端渲染 (SSR) 与 hydration 的性能。

• 管理缓存同步，避免路由预加载与查询过期时间配置之间的冲突。

• 为实现基于 suspense 的数据加载与 mutation 失效工作流程提供明确准则。

• 在复杂的应用程序架构中标准化错误边界与加载状态。

• 专为使用 TypeScript 的应用程序而设计，以最大化 TanStack Router 类型安全路由的优势。

• 需要在路由器的上下文中小心设置 QueryClient，以利于正确的 SSR 流式传输。

• 使用此技能来调试与重复获取、过期数据或页面转换期间 hydration 不正确相关的问题。

• 代理程序的输入包括应用程序的路由器与查询配置文件；输出提供重构的代码片段、结构建议以及架构对齐检查。

• 遵守 Agent Skills 格式，使其可与 Claude Code 等 AI 代码代理程序直接兼容，后者可在代码库分析期间自动验证这些集成规则。