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 程式碼代理程式直接相容，後者可在程式碼庫分析期間自動驗證這些整合規則。