tanstack-integration-best-practices

TanStack 統合のベストプラクティス

TanStack Query、Router、Start を効果的に連携させるためのガイドラインです。これらのパターンにより、スタック全体で最適なデータフロー、キャッシュの連携、型安全性を実現できます。

適用する場面

• 新しい TanStack Start プロジェクトをセットアップするとき
• TanStack Query を TanStack Router と連携するとき
• クエリのハイドレーションを使った SSR を設定するとき
• Router と Query の間でキャッシュを連携するとき
• 型安全なデータ取得パターンを設定するとき

優先度別のルールカテゴリ

優先度	カテゴリ	ルール	影響
CRITICAL	セットアップ	3 ルール	基盤となる設定
CRITICAL	SSR 連携	1 ルール	Router + Query の SSR 設定
HIGH	データフロー	4 ルール	正しいデータ取得パターン
MEDIUM	キャッシュ	3 ルール	パフォーマンスの最適化
MEDIUM	SSR	2 ルール	追加の SSR パターン

クイックリファレンス

セットアップ（プレフィックス：setup-）

• setup-query-client-context — QueryClient を router context 経由で渡す
• setup-provider-wrapping — QueryClientProvider で正しくラップする
• setup-stale-time-coordination — Router と Query の staleTime を連携させる

データフロー（プレフィックス：flow-）

• flow-loader-query-pattern — ensureQueryData とともに loader を使う
• flow-suspense-query-component — コンポーネントで useSuspenseQuery を使う
• flow-mutations-invalidation — ミューテーションとクエリの無効化を連携させる
• flow-server-functions-queries — クエリ関数にサーバー関数を使う

キャッシュ（プレフィックス：cache-）

• cache-single-source — キャッシュ管理を TanStack Query に任せる
• cache-preload-coordination — Router と Query の間でプリロードを連携させる
• cache-invalidation-patterns — 統一された無効化パターン

SSR 連携（プレフィックス：ssr-）

• ssr-dehydrate-hydrate — setupRouterSsrQueryIntegration を使って SSR を自動化する

追加の SSR（プレフィックス：ssr-）

• ssr-per-request-client — リクエストごとに QueryClient を作成する
• ssr-streaming-queries — クエリでストリーミングを処理する

使用方法

rules/ ディレクトリ内の各ルールファイルには、次の内容が含まれています。

1. 説明 — このパターンが重要な理由
2. 悪い例 — 避けるべきアンチパターン
3. 良い例 — 推奨される実装
4. コンテキスト — このルールを適用する場面、または適用を省略する場面

リファレンス全文

詳しいガイダンスとコード例については、rules/ ディレクトリ内の個々のルールファイルを参照してください。