jotai

Jotai

概要

新しいコードでは Jotai v3 を基準にしてください。既存のプロジェクトでは、バージョンに依存する助言をする前に、インストール済みの Jotai と拡張機能のバージョンを確認してください。依頼された動作、アーキテクチャ、依存関係の選択を維持し、リファクタリングの指針はタスクに役立つ場合にのみ使用してください。

ワークフロー

• コードを変更する前に、状態の所有者、各読み取り側と書き込み側で使われるストア、atom の同一性、非同期処理の動作、関連するテストを確認してください。
• 依頼を満たす最小限の変更を選んでください。計算値は導出し、必要に応じて独立して更新される状態を分離し、コマンドに共通の更新経路が役立つ場合は名前付きアクション atom を使用してください。
• 適切なレベルで動作を検証してください。状態ロジックと分離には vanilla ストアのテストを、サブスクリプションとユーザー操作にはコンポーネントテストを使用します。実用的な場合は既存のテスト構成に合わせてください。

コアとなる不変条件

• atom の設定オブジェクトは参照によって状態を識別し、値はストアに属します。レンダー間で atom の設定オブジェクトを安定させ、状態フローに関わるすべての箇所で同じストアを使用してください。
• オブジェクトと配列の値はイミュータブルに置き換えてください。Jotai は値の変更を検出するために Object.is を使用します。値を変更したうえで同じ参照を設定すると、更新が抑制されることがあります。
• 読み取り関数の get は依存関係を追跡します。書き込み関数の get はリアクティブなサブスクリプションを確立せずに読み取ります。読み取りには無関係な副作用を含めないでください。
• 読み取りには useAtomValue、書き込みには useSetAtom、両方には useAtom を使用してください。命令型の連携には vanilla の get／set／sub を使用します。読み取るだけでは atom はマウントされません。
• 初期化とサブスクリプションのライフタイムを明示してください。onMount は atom のサブスクリプションに従い、モジュールの読み込みや setter の呼び出しには従いません。サーバーではリクエストごとに状態を分離してください。
• ユーティリティよりも、まず基本的な atom の合成を優先してください。必要なセマンティクスをより明確に表現できる場合は、インストール済みのメジャーバージョンとの互換性を確認したうえで、ユーティリティや拡張機能を追加してください。

リファレンスの参照先

タスクに合致するファイルだけを読んでください。

• references/atom-modeling.md：atom の境界、派生 atom、アクション atom、書き込み可能なアダプター、リセット、ストレージ、ファミリー形式のパラメーター化 atom の判断に使用します。
• references/react-usage.md：フックの選択、Provider／ストアのスコープ、vanilla の連携、SSR、ハイドレーション、動的な atom の作成、コンポーネントのアーキテクチャに使用します。
• references/async-and-side-effects.md：Suspense、非同期読み取り、非同期アクション、中止シグナル、Suspense を使わない状態、更新フロー、外部副作用に使用します。
• references/performance-and-large-state.md：レンダーの調整、selectAtom、focusAtom、splitAtom、大きなオブジェクト、リスト、依存関係グラフの深さに使用します。
• references/typescript-and-testing.md：TypeScript の型推論、書き込み可能な atom の引数型、ExtractAtomValue、テスト戦略に使用します。
• references/utilities-decision-guide.md：ストレージ、SSR ハイドレーション、リセット可能／デフォルト atom、遅延 atom、コールバック、reducer、select、split、family の移行など、組み込みユーティリティの選択に使用します。
• references/extensions-decision-guide.md：TanStack Query、optics、Immer、effects、location、scope、cache、XState、GraphQL／RPC、外部ストアのブリッジなど、拡張パッケージの選択に使用します。
• references/tools-and-debugging.md：デバッグ、ラベル、React Refresh、バンドラー連携に用いる Devtools、Babel、SWC、Rolldown のサポートを選ぶ際に使用します。
• references/recipes-decision-guide.md：debounce、リスナー、broadcast、compare、toggle、カスタムフック、reducer フック、atom effects など、公式レシピを使用または応用するタイミングの判断に使用します。
• references/version-migration.md：v2 から v3 への移行に使用します。React／TypeScript／Node の要件引き上げ、ESM 専用パッケージ化、削除された API とその代替、jotai/vanilla/internals の変更が記載されています。

互換性とソースの検証

この改訂版は Jotai 3.0.1 を基準に作成されており、両者に違いがある場合は Jotai 2.20.x についても説明しています。バージョンに依存する API の案内を行う前に、対象プロジェクトにインストールされている Jotai と拡張パッケージのバージョンを確認し、エクスポートされている型、ソース、または該当バージョンのドキュメントとテストを調べてください。現在のドキュメントがインストール済みのバージョンと一致するとは限りません。