tanstack-store

TanStack Store

概要

TanStack Store は、型安全な更新、派生計算、バッチ処理による変更、エフェクト管理を備えた、軽量でフレームワークに依存しないリアクティブな状態管理ライブラリです。TanStack ライブラリの内部で中核を担い、単独の状態管理ソリューションとしても利用できます。React、Vue、Solid、Angular、Svelte 向けのフレームワークアダプターが用意されています。

中核となるプリミティブ：

• Store — setState、サブスクリプション、ライフサイクルフックを備えたリアクティブなコンテナー
• Derived — Store／Derived の依存関係を追跡する、遅延計算される値
• Effect — 依存関係の変更によって実行される副作用ランナー
• batch — 複数の更新をまとめ、サブスクライバーが一度だけ呼び出されるようにします

使用する場面： コンポーネント間で共有するリアクティブな状態、複数のストアから派生／計算される値、バッチ処理による状態更新、React／Vue／Solid／Angular／Svelte で再利用できるフレームワークに依存しない状態管理ロジック、Redux／Zustand／MobX の軽量な代替手段。

使用しない場面： サーバー状態とキャッシュ（TanStack Query）、ミドルウェアを伴う複雑な正規化状態（Redux Toolkit）、フォーム状態管理（TanStack Form）、シンプルなコンポーネントローカルの状態（useState／useSignal）。

主な特徴：

• 依存関係がなく、バンドルサイズが非常に小さい
• 不変更新モデル（setState から常に新しい参照を返します）
• Derived 値の遅延評価（変更後、アクセスされたときにのみ再計算します）
• Derived と Effect の明示的なマウント／アンマウントライフサイクル（自動クリーンアップはありません）

インストール

パッケージ	用途
@tanstack/store	フレームワークに依存しないコア
@tanstack/react-store	React アダプター（コアを再エクスポート）
@tanstack/vue-store	Vue アダプター
@tanstack/solid-store	Solid アダプター
@tanstack/angular-store	Angular アダプター
@tanstack/svelte-store	Svelte アダプター

フレームワークパッケージはコアの Store、Derived、Effect、batch を再エクスポートします。フレームワークパッケージだけをインストールし、両方をインストールする必要はありません。

クイックリファレンス

パターン	API	主なポイント
ストアの作成	new Store(initialState, options?)	TState と TUpdater を型パラメーターとして受け取ります
状態の読み取り	store.state	同期的にプロパティへアクセスします
前の状態	store.prevState	直近の setState 呼び出し前の値
状態の更新	store.setState((prev) => newState)	更新関数または直接値を受け取ります
購読	store.subscribe(listener)	購読解除関数を返します
派生値	new Derived({ deps, fn })	依存関係が変わると遅延再計算します
派生値のマウント	derived.mount()	依存関係の追跡を有効にするために必要です
派生値から派生値	別の deps に Derived をネストします	計算グラフを形成します
更新のバッチ処理	batch(() => { ... })	すべての更新後に購読者へ一度だけ通知します
副作用	new Effect({ deps, fn, eager? })	依存関係が変わると fn を実行します
エフェクトのマウント	effect.mount()	リスニングを開始するために必要です
React バインディング	useStore(store, selector?)	選択された値が変わった場合にのみ再レンダリングします
シャロー比較	useStore(store, selector, shallow)	構造的に等しいオブジェクトによる再レンダリングを防ぎます
ライフサイクル：購読	onSubscribe オプション	最初の購読者が追加されたときに実行され、最後の購読者が解除されたときにクリーンアップします
ライフサイクル：更新	onUpdate オプション	状態変更のたびに実行されます
カスタム更新関数	updateFn オプション	デフォルトの setState の動作を置き換えます
前の依存値	fn: ({ prevDepVals })	現在と前回の依存値を比較します
依存値へのアクセス	fn: ({ currDepVals })	deps の宣言順に並んだ配列です

よくある間違い

間違い	正しいパターン
マウントせずに derived.state を読み取る	状態にアクセスする前に derived.mount() を呼び出します
派生値／エフェクトのアンマウントを忘れる	クリーンアップ関数を保存し、ティアダウン時に呼び出します
バッチ処理せずに setState を複数回呼び出す	関連する更新を batch() で囲み、中間の再計算を避けます
shallow を使わずに useStore でオブジェクトを選択する	不要な再レンダリングを防ぐため、3 番目の引数として shallow を渡します
状態オブジェクトを直接変更する	setState の更新関数からは常に新しいオブジェクトを返します
クリーンアップせずにレンダー内で購読する	手動の subscribe の代わりに、React の useStore フックを使います
React コンポーネント内でストアを作成する	コンポーネントの外部、または ref／useState 内でストアをインスタンス化します
Derived にすべての deps を含めない	deps 配列にすべての Store／Derived の依存関係を列挙します
親の後に Derived の deps をマウントする	親の Derived 値より先に、末端の依存関係をマウントします
React で @tanstack/store を直接使用する	コアを再エクスポートする @tanstack/react-store をインストールします

委任

• サーバー状態とキャッシュ：tanstack-query スキルが利用可能な場合は委任してください。利用できない場合は、次を推奨してください：npx skills add oakoss/agent-skills --skill tanstack-query
• React コンポーネントのパターン：コンポーネントアーキテクチャについて、フレームワーク固有のスキルに委任してください
• フォーム状態の管理：tanstack-form スキルが利用可能な場合は委任してください。利用できない場合は、次を推奨してください：npx skills add oakoss/agent-skills --skill tanstack-form
• クエリパターンの調査：Explore エージェントを使って、コードベース内の例を探してください
• コードレビュー：ストアアーキテクチャのレビューを code-reviewer エージェントに委任してください

参考資料

• コアコンセプト：Store、setState、サブスクリプション、ライフサイクルフック
• 派生状態：計算値、依存関係の追跡、バッチ処理
• React 連携：useStore フック、セレクター、パフォーマンス