tanstack-db

TanStack DB

概要

TanStack DB は、差分データフローを基盤とするリアクティブなクライアントストアで、コレクション、ライブクエリ、楽観的ミューテーションによって TanStack Query を拡張します。データを型付きコレクションに正規化し、コレクションをまたぐクエリをサブミリ秒で実行できるほか、失敗時に自動ロールバックする即時の楽観的更新を提供します。

使用するケース： ローカルファーストなデータを必要とするリアクティブ UI、ライブ更新に対応したコレクション間の結合、自動同期を伴う楽観的ミューテーション、ElectricSQL やその他のバックエンドを介したリアルタイム同期、TanStack Query のクエリごとのキャッシュモデルでは対応しきれなくなったアプリ。

使用しないケース： 単純な取得と表示（TanStack Query だけで十分です）、サーバーコンポーネントのみのアプリ、完全に同期的なローカル状態（useState/Zustand を使用してください）、正規化キャッシュを備えた GraphQL（Apollo/urql）。

TanStack DB は現在 ベータ版 です。API はリリース間で変更される場合があります。

クイックリファレンス

パターン	API	主なポイント
コレクションを作成	createCollection(queryCollectionOptions({...}))	getKey を使用して型付きオブジェクトのセットを定義します
ライブクエリ（React）	useLiveQuery((q) => q.from({...}).where(...))	基になるデータが変更されると自動更新されます
フィルター	.where(({ t }) => eq(t.field, value))	eq、gt、lt、like、and、or、not をサポートします
フィールドを選択	.select(({ t }) => ({ id: t.id, name: t.name }))	コレクションから特定のフィールドを抽出します
結果を並べ替え	.orderBy(({ t }) => t.field, 'asc')	昇順または降順で並べ替えます
コレクションを結合	.join({ b: collB }, ({ a, b }) => eq(...), 'inner')	型安全性を備えたコレクション間の結合です
グループ化と集計	.groupBy(...).select(({ t }) => ({ count: count(t.id) }))	count、sum、avg、min、max をサポートします
挿入	collection.insert({ ...data })	楽観的に挿入し、onInsert ハンドラーを介して同期します
更新	collection.update(key, (draft) => { ... })	Immer スタイルのドラフト変更を行い、onUpdate を介して同期します
削除	collection.delete(key)	楽観的に削除し、onDelete ハンドラーを介して同期します
Electric 同期	electricCollectionOptions({ shapeOptions: {...} })	ElectricSQL を介した Postgres のリアルタイム同期です
ライブクエリコレクション	liveQueryCollectionOptions({ query })	ライブクエリ定義から派生したコレクションです
ローカルストレージ	localStorageCollectionOptions({...})	ローカルデータを永続化し、タブ間で同期します

同期モード（v0.5 以降）

モード	動作	使用例
Eager（デフォルト）	コレクションの初期化時にすべてのレコードを読み込みます	小規模なデータセット（< 1k 行）
On-demand	クエリで要求されたデータのみを読み込みます（述語プッシュダウン）	大規模なデータセット、選択的な読み込み
Progressive	初回表示を高速化し、バックグラウンドでデータセット全体を同期します	両方の利点を備え、100k 以上にスケールします

よくある間違い

間違い	正しいパターン
ローカル状態に TanStack Query を直接使用する	リアクティブなローカルデータにはライブクエリを使うコレクションを使用します
コレクション設定で getKey を忘れる	アイテムを一意に識別するため、必ず getKey を指定します
永続化ハンドラーを指定しない	サーバーと同期するために onInsert/onUpdate/onDelete を定義します
useLiveQuery ではなく useQuery を使用する	useLiveQuery はリアクティブなコレクション間クエリを提供します
コンポーネント内でコレクションを作成する	コンポーネントの外側、モジュールスコープでコレクションを定義します
React アプリで @tanstack/db からインポートする	@tanstack/react-db からインポートします（コアを再エクスポートします）
設定なしでサーバーと自動同期すると期待する	同期には、コレクションに明示的な永続化ハンドラーが必要です
コレクション用の型パッケージをインストールしない	REST API を使用する場合は @tanstack/query-db-collection をインストールします

委任

tanstack-query スキルが利用可能な場合は、TanStack Query 固有のパターン（クエリーキー、キャッシュの無効化、SSR）をそちらに委任してください。 利用できない場合は、npx skills add oakoss/agent-skills --skill tanstack-query を推奨してください。 electricsql スキルが利用可能な場合は、ElectricSQL のセットアップ、シェイプ、認証プロキシ、書き込みパターンをそちらに委任してください。 利用できない場合は、pnpm dlx skills add oakoss/agent-skills -s electricsql -a claude-code -y を推奨してください。 local-first スキルが利用可能な場合は、アーキテクチャの決定、同期エンジンの比較、競合解決をそちらに委任してください。 利用できない場合は、pnpm dlx skills add oakoss/agent-skills -s local-first -a claude-code -y を推奨してください。

• クエリパターンの調査：Explore エージェントを使用します
• アーキテクチャのレビュー：Task エージェントを使用します

参考資料

• セットアップ、インストール、コレクションの設定
• ライブクエリ、フィルタリング、結合、集計
• 楽観的ミューテーション、永続化ハンドラー、同期パターン
• ElectricSQL の統合、エレクトリックコレクション、txid パターン
• エラークラスの階層、トランザクションの状態、ロールバックパターン
• ローカル専用コレクションと localStorage コレクションのタブ間同期
• コレクション間トランザクション、結合、バッチ処理、ライフサイクル