tanstack-integration

TanStack の統合 — ライブラリを戦略的に採用する

理念：「金づちを持つ人には、すべてが釘に見える」という状態を避けましょう。まずはバニラで始め、明確なメリットがある場合にのみ TanStack を戦略的に採用します。

**タイミング：**バニラの Next.js／React／Tailwind でアプリがすでに十分に動作している段階で使います。

---

TanStack とは？

TanStack は、Web アプリケーション向けの高品質なライブラリ群です。

ライブラリ	目的
TanStack Query	サーバー状態の管理、キャッシュ、同期
TanStack Table	ヘッドレスなテーブル／グリッドのロジック
TanStack Form	フォーム状態の管理と検証
TanStack Router	型安全なルーティング
TanStack Virtual	大規模なリストの仮想化
TanStack Ranger	範囲／スライダーコンポーネント

---

アンチパターン：時期尚早な採用

これは避けましょう：

1. 新しいプロジェクトを始める
2. すぐに TanStack ライブラリをすべてインストールする
3. すべてを TanStack のパターンに無理に当てはめる
4. 過剰に設計されたコードになってしまう

よくない理由：

• すべての機能に TanStack が必要なわけではありません
• シンプルな解決策で済むところに複雑さを加えてしまいます
• メリットがないのに、コードが理解しにくくなります
• 「金づちを持つ人」には、あらゆる問題が釘に見えてしまいます

---

正しいパターン：戦略的な採用

代わりにこうしましょう：

1. バニラの Next.js 16、React 19、Tailwind で構築する
2. アプリが適切に動作する状態にする
3. TanStack 分析プロンプトを実行する
4. 明確な改善効果がある場合にのみ TanStack を採用する
5. これを何度か繰り返す

---

正確なプロンプト — TanStack 分析

Ok, I want you to look through the ENTIRE project and look for areas where, if we leveraged one of the many TanStack libraries (e.g., query, table, forms, etc), we could make part of the code much better, simpler, more performant, more maintainable, elegant, shorter, more reliable, etc. Use ultrathink

---

各 TanStack ライブラリを使う場面

TanStack Query

適しているケース：

• キャッシュが必要な API 呼び出し
• 頻繁に取得するデータ
• 楽観的更新
• バックグラウンドでの再取得
• キャッシュを伴うページネーション
• 無限スクロール

使わなくてよいケース：

• 一度だけ行うシンプルなデータ取得
• 静的データ
• 同期が不要なデータ

TanStack Table

適しているケース：

• ソート／フィルタリング機能を備えた複雑なデータテーブル
• ページネーションを備えたテーブル
• 列幅の変更／列の並べ替え
• 行の選択
• 展開可能な行
• サーバーサイドのデータテーブル

使わなくてよいケース：

• シンプルな静的テーブル
• 行数が 20 行未満のテーブル
• インタラクティブな機能が不要な場合

TanStack Form

適しているケース：

• 複雑な複数ステップのフォーム
• 複雑な検証を伴うフォーム
• 動的フィールドを含むフォーム
• 非同期検証を伴うフォーム
• ウィザード形式のワークフロー

使わなくてよいケース：

• シンプルな問い合わせフォーム
• フィールド数が 3～4 個のフォーム
• 基本的な検証だけで済む場合

TanStack Router

適しているケース：

• 型安全なルーティングが必要な大規模アプリ
• 複雑なネストされたルート
• ルートベースのコード分割
• 検索パラメーターの管理

使わなくてよいケース：

• Next.js App Router を使用している場合（すでに十分に優れています）
• シンプルなナビゲーションで済む場合
• ルート数が少ない場合

TanStack Virtual

適しているケース：

• 1000 件以上の項目を含むリスト
• 無限スクロールのビュー
• 大規模なデータグリッド
• チャットメッセージのリスト

使わなくてよいケース：

• 項目数が 100 件未満のリスト
• すでに別の方法でウィンドウ化している場合
• 使用しなくてもパフォーマンスに問題がない場合

---

統合ワークフロー

ステップ 1：アプリを動作させる

まずはバニラのパターンでアプリを構築します：

• API 呼び出しには fetch または axios を使う
• ネイティブのフォーム処理
• シンプルな HTML テーブル
• Next.js のルーティング

ステップ 2：分析を実行する

Claude Code + Opus 4.5 または Codex + GPT 5.2（高い推論強度）で TanStack 分析プロンプトを使います。

ステップ 3：提案を評価する

モデルが導入の機会を特定します。それぞれについて、次の点を確認します：

• 複雑さに見合うメリットがありますか？
• 現在の解決策に実際の問題がありますか？
• 保守性は向上しますか？

ステップ 4：選択的に採用する

明確なメリットがある場合にのみ採用します。次のような使い方で問題ありません：

• TanStack Query は使い、Table は使わない
• すべてのテーブルではなく、複雑なテーブル 1 つにだけ Table を使う
• バニラのアプローチと TanStack のアプローチを組み合わせる

ステップ 5：繰り返す

変更後にもう一度分析を実行します。新たな導入の機会が見つかることがあります。

---

このタスクに最適なモデル

モデル	設定
Claude Code + Opus 4.5	ultrathink を使用
Codex + GPT 5.2	高または非常に高い推論強度

---

改善例

変更前：手動でのデータ取得

// Vanilla approach
const [data, setData] = useState(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);

useEffect(() => {
  fetch('/api/users')
    .then(res => res.json())
    .then(setData)
    .catch(setError)
    .finally(() => setLoading(false));
}, []);

変更後：TanStack Query

// TanStack Query approach
const { data, isLoading, error } = useQuery({
  queryKey: ['users'],
  queryFn: () => fetch('/api/users').then(res => res.json()),
});

メリット：

• キャッシュ機能が組み込まれています
• 自動で再取得します
• リクエストを重複排除します
• DevTools に対応しています

変更前：複雑なテーブルロジック

// Vanilla approach with manual sorting, filtering, pagination
// ... 200+ lines of state management

変更後：TanStack Table

// TanStack Table handles sorting, filtering, pagination
const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getSortedRowModel: getSortedRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
});

メリット：

• ヘッドレス（UI は自分で制御できます）
• テーブルロジックをすべて処理します
• 動作に一貫性があります
• コード量が大幅に減ります

---

TanStack の作業用 Beads の作成

br create "Evaluate TanStack Query opportunities" -t enhancement -p 3
br create "Migrate user data fetching to TanStack Query" -t enhancement -p 2
br create "Implement data table with TanStack Table" -t feature -p 2
br create "Add TanStack Virtual to chat message list" -t performance -p 2

---

プロンプトの完全なリファレンス

TanStack の分析

Ok, I want you to look through the ENTIRE project and look for areas where, if we leveraged one of the many TanStack libraries (e.g., query, table, forms, etc), we could make part of the code much better, simpler, more performant, more maintainable, elegant, shorter, more reliable, etc. Use ultrathink

クエリに焦点を当てた分析

Look through the project for data fetching patterns that would benefit from TanStack Query. Consider caching needs, refetching patterns, and optimistic updates. Identify the top 3 opportunities. Use ultrathink.

テーブルに焦点を当てた分析

Look through the project for table/grid components that would benefit from TanStack Table. Consider sorting, filtering, pagination, and column management needs. Identify candidates. Use ultrathink.

---

ヒント

1. 過剰に採用しない — バニラのパターンで十分な場合もあります
2. メリットを測定する — 実際にコードが改善されますか？
3. チームの習熟度を考慮する — TanStack には学習曲線があります
4. バンドルサイズを確認する — 必要なものだけをインポートします
5. ドキュメントを読む — TanStack のドキュメントは優れています