react

React の規約 — フレームワークスキル

モダンな React 向けのルールです。関数コンポーネント、フック、サーバーコンポーネント、アクション、React Compiler を対象とします。core-typescript と architecture-and-design が一般的な表現で定めているルールを、React に即した形で示します。

基盤となるスキル。 core-typescript（言語ルール）と architecture-and-design（設計）です。タスクがそれらのレイヤーに関わる場合にのみ、関連するスキルを読み込んでください。読み込まれていない場合は、一般知識に基づいてそのレイヤーを適用し、作業を中断しないでください。

この SKILL.md は単独で機能します。以下の ルールセット が、完全かつ適用可能なルールの一覧です。各 references/<topic>.md には、そのグループの背景説明と ❌ / ✅ のコード例が記載され、references/worked-example.md にはレビュー全体の例が記載されています。実行環境が許す場合は、詳しく確認するために開いてください。

---

このスキルの使い方

タスクに合ったモードを選び、手順どおりに進めてください。

モード	手順
生成 — 新しいコンポーネントまたはフックを作成する	1. レンダリングを純粋に保ち、props に型を付けます（purity）。 2. useEffect を書く前に effects を確認します。ほとんどの場合、useEffect は不要です。 3. レンダリング中に state を導出し、key でリセットします（state）。 4. ルールセットをチェックリストとして実行します。引き渡す前に、不適合箇所をすべて修正してください。
レビュー — プルリクエストまたは差分を確認する	1. 差分に対してルールセットを実行します。 2. 不適合箇所ごとに、以下の出力形式で指摘を 1 件記述します。 3. 指摘は must-fix を先に、その後に consider の順で並べます。 4. 不適合箇所がなければ、その旨を 1 行で伝えます。指摘を捏造しないでください。
移行 — レガシーな React をモダン化する	1. React 19 の型 codemod を実行し、続けて forwardRef と <Context.Provider> の codemod を実行します。 2. eslint-plugin-react-hooks（v6 以降、recommended）を有効にして、すべての警告を修正します。 3. React Compiler を導入し、参照同一性を保つためだけに手書きされた useMemo / useCallback を削除します。 4. 変更の種類ごとにコミットを分けます。テストが通る状態を保ってください。

出力形式

1 行に指摘を 1 件記述してください。

<severity> · <topic> · <file>:<line> — <what is wrong>. <the fix as an action>.

• <severity> は must-fix（このスキルのルールまたは lint ルールへの違反）か、consider（問題はないものの、ルールでは別の形式を推奨）です。
• <topic> はルールセットのトピックスラッグです（effects、state、data-fetching、…）。

すべてのモードに共通するルール

• ルールを適用する際は、ルールセットのトピック名を明記してください。
• 前の API よりも現行の API を優先します。forwardRef より props としての ref、<Context.Provider> より <Context>、手動の送信 useEffect よりアクションを使います。
• useEffect を使う前に、コードが実行される理由を考えてください。答えが「コンポーネントが画面に表示されており、外部システムとの同期が必要だから」でなければ、Effect に含めるべきではありません。

---

ルールセット

purity → references/purity.md

• レンダリングは純粋です。props、state、前回のレンダリングの値を変更せず、レンダリング本体に副作用がなく、アプリのツリーが <StrictMode> でラップされています。
• 同じ props、state、context からは、同じ JSX が生成されます。
• props は React.FC ではなく type または interface で定義され、children は ReactNode として型付けされ、イベントハンドラーは対応する React のイベント型で型付けされています。
• ref は通常の prop として受け取り、新しいコンポーネントに forwardRef を使いません。
• 1 ファイルにつき 1 コンポーネントとし、ファイル名はコンポーネント名に一致させます。JSX のためだけに import React を使いません（"jsx": "react-jsx"）。
• useId() はラベルまたは aria-* の id に使用し、リストキーには使用しません。要素の選択とアクセシブルな名前は accessibility に従います。
• eslint-plugin-react と eslint-plugin-react-hooks（v6 以降、recommended）が有効で、すべての警告が無効化されずに修正されています。

hooks → references/hooks.md

• すべてのフックは、早期の return より前に、コンポーネントまたは別のフックのトップレベルで呼び出します。条件分岐、ループ、ネストした関数、イベントハンドラー、try / catch、または useMemo / useReducer / useEffect に渡す関数内では呼び出しません。
• フックは関数コンポーネントまたはカスタムフックからのみ呼び出します。
• 共有する状態付きロジックは、useX という名前のカスタムフックにまとめ、安定した型付きの値を返します。
• useEffect / useMemo / useCallback の依存配列は完全で、省略されていません。

state → references/state.md

• state はそれを使うコンポーネント内に配置し、2 つ目のコンポーネントが同じ値を必要とする場合にのみ持ち上げます。
• props や他の state から導出できる値は、state にコピーせず、レンダー中に計算します。
• props を state にミラーリングしません。サブツリーをリセットするには、Effect でフィールドをクリアするのではなく、key を使います。
• state をその場で変更しません。新しい値を作成して設定します。
• 次の値が前の値に依存する場合は、更新関数形式（setX(x => …)）を使います。
• 初期値の計算が高コストな場合は、遅延形式 useState(() => build()) を使います。
• 複数のフィールドをまとめて変更する場合、または次の state がイベントと現在の state の両方に依存する場合は、useReducer を使います。
• 外部ストアは useState と購読用 Effect の組み合わせではなく、useSyncExternalStore で読み取ります。

effects → references/effects.md

• 次の用途には Effect を使いません。レンダー用のデータ変換、コストの高い計算（useMemo）、prop 変更時の state リセット（key）、ユーザーイベント、POST、state 更新の連鎖、親への通知、アプリの初期化処理。
• Effect は、外部システム（ウィジェット、ソケット、サブスクリプション、ドキュメントタイトル）との同期にのみ使います。
• すべての Effect にセットアップを取り消すクリーンアップを設けます。同期ごとに Effect を 1 つ使います。
• データを取得する Effect では、古いレスポンスへの対策（AbortController または無視フラグ）を設けます。より望ましいのは、キャッシュライブラリを使う方法です（data-fetching を参照）。
• 再利用可能な Effect はカスタムフックに切り出します。
• 再購読せずに最新の値を読み取るには、不適切な依存配列ではなく、Effect Event（useEffectEvent）を使います。

refs → references/refs.md

• useRef は、レンダーをまたいで保持する必要があり、かつレンダーを発生させない値（DOM ノード、タイマー ID、前の値）にのみ使います。
• レンダー中に ref.current を読み書きしません。イベントハンドラーまたは Effect 内でのみ行います。
• ref は通常の prop です。forwardRef は使いません。
• 命令型 API は useImperativeHandle で公開し、focus や scrollIntoView のように小さく、名前を付けます。
• リスナーを登録する ref コールバックは、リスナーを解除するクリーンアップ関数を返します。
• ナビゲーション後、非同期アクション後、ダイアログを開いたときは、ref を使ってフォーカスを移動します。
• ref は最後の手段です。まず state または prop で対応できないか検討します。

context → references/context.md

• Context には、更新頻度が低く、広く参照されるデータ（テーマ、ロケール、現在のユーザー、DI コンテナー）のみを保持します。
• 更新頻度の高い値は、独立した Context、またはローカル state かセレクターを備えたストアに置きます。広範囲で使われる Context には置きません。
• プロバイダーには <Context.Provider> ではなく、<Context value={…}>（React 19）を使います。
• Context は useContext で読み取ります。読み取りを条件付きにする必要がある場合にのみ、use(Context) を使います。
• Context の value はメモ化します（または React Compiler を有効にします）。インラインのオブジェクトリテラルは使いません。

data-fetching → references/data-fetching.md

• 単独の useEffect でデータを取得しません。フレームワークのローダー、キャッシュライブラリ（TanStack Query、SWR）、またはキャッシュで作成した promise を使う use(promise) を使います。
• 各リクエストには、入力値から導出した安定したキャッシュキーを設定します。
• 非同期の読み取り処理は、実際に機能するフォールバックを備えた <Suspense> で囲み、互いに独立した各領域をエラーバウンダリーで囲みます。
• レンダーエラーはクラスのバウンダリーまたは react-error-boundary で捕捉します。フックはありません。
• 緊急性の低い更新には useTransition / useDeferredValue を使います。
• ミューテーションの結果を使ってキャッシュを更新します。useOptimistic はロールバック処理がある場合にのみ使います。

フォーム → references/forms.md

• 送信は useActionState を使った <form action={submitAction}> で制御し、子コンポーネントの保留状態には useFormStatus を使います。
• 楽観的な行には useOptimistic を使います（失敗時に元に戻ります）。手作業で楽観的な状態を実装しません。
• 入力が、使用中に制御コンポーネントと非制御コンポーネントの間で切り替わることはありません。フィールドのデフォルトのモードについては component-api-design、 controlled-uncontrolled を参照してください。
• バリデーターはサーバーが使用するものと同じスキーマから作成し、サーバーでも再検証します。
• 送信に失敗しても入力値を保持し、各フィールドのエラーを該当するフィールドに対応付けます。

サーバーとクライアント → references/server-client.md

• コンポーネントはデフォルトで Server Component です（ディレクティブなし）。コンポーネント内に状態、エフェクト、ブラウザー API、ハンドラーを含めません。
• データが必要な Server Component は async にし、レンダー時に await します（データベースやファイルを直接読み取ります）。自身のデータを取得するためのクライアントとの往復通信を 作りません。
• 'use client' はページやレイアウトではなく、最小のインタラクティブなリーフに配置します。
• サーバー関数には 'use server' を指定し、Action として呼び出します。境界を越える props はシリアライズ可能にします（Server Actions 以外の関数や、 クラスのインスタンスは渡しません）。
• サーバー専用モジュール（DB クライアント、シークレット、fs）が 'use client' ファイルから参照可能な状態にしません。server-only でこれを強制します。
• データ取得は Server Component またはローダーで行い、その結果を下位に渡します。

レンダリング → references/rendering.md

• React Compiler を有効にします。有効でない場合、memo／useMemo／useCallback は Profiler で計測したパスにのみ使用します。
• レンダー中に新しいオブジェクト／配列／関数を作成し、メモ化された子コンポーネントに渡しません。
• key にはデータに含まれる安定した ID を使い、配列のインデックスは使いません（architecture-and-design、frontend-practices）。
• ルートは lazy() と <Suspense> でコード分割し、数百行を超えるリストは仮想化します。
• <title>／<meta>／<link rel> は、それらを所有するコンポーネント内でレンダーします（React 19 が自動的に上位へ移動します）。
• モーダル／ツールチップ／トーストは createPortal 経由でレンダーし、React ツリー内にとどめます。

テスト → references/testing.md

• React Testing Library でレンダーし、ロールとアクセシブルネームでクエリします。
• 操作には fireEvent ではなく、@testing-library/user-event を使います（await します）。
• データの代わりにモックしたモジュールやフックを使いません。境界のルール（MSW）については test-quality、test-doubles を参照してください。
• アサーションは状態、props、呼び出し回数ではなく、レンダーされた出力を対象にします。非同期処理には findBy*／waitFor を使います。
• カスタムフックは、それを使用するコンポーネントを通じてテストします。使用するコンポーネントがない場合に限り renderHook を使います。
• createPortal のコンテンツは render() の戻り値ではなく、screen（ドキュメント全体）を通じてクエリします。
• シャローレンダリング、Enzyme、広範なスナップショットは使いません。
• 各テストは test-quality Ruleset も満たす必要があります。内部実装ではなくレンダーされた動作を検証し、意味のあるアサーションを含み、決定的であること。このグループは React の仕組みを扱い、test-quality はテスト自体を評価します。

---

制限事項

このスキルはReactフレームワークのルールを扱います。以下は対象外です。

• 言語のルール（core-typescriptを参照）およびフレームワークに依存しないアーキテクチャ（architecture-and-designを参照）。
• 特定のフレームワークのルーター、ローダー、メタデータAPI（Next.js、React Router、TanStack Start）。ここに記載するRSCとデータ取得のルールは適用されますが、各フレームワーク固有の規約は対象外です。
• ストアライブラリ（Redux Toolkit、Zustand、Jotai）。architecture-and-designの状態管理の階層を使い、必要とされる場合にのみストアを選んでください。
• アクセシビリティの詳細。useIdとフォーカス管理については該当する箇所で触れますが、包括的な視点はaccessibilityで扱います。
• React Nativeとアニメーションライブラリ。スタイリングはstyling-and-design-tokens、i18n（react-intlの方針）はi18n-and-localization、読み込みとインタラクションのコストはweb-performanceで扱います。
• その他のフレームワーク。兄弟スキルはangularとvueです。ここに記載するすべてのルールはReact固有です。

React Compilerは安定版（1.0）です。ここに記載するルールは、React Compilerを採用することを前提としています。採用していない場合、手動のメモ化に関するルールはrenderingを参照してください。

---

参考資料

このスキルは、以下と連携します。

• core-typescript — 言語の基盤です。JSXやフックを使っても、そのルールは免除されません。
• architecture-and-design — 設計レイヤーです。意見が対立した場合、設計はこのスキルに従い、React APIは本スキルに従います。
• accessibility — UIのレビュー視点です。Reactで利用できるツールはuseId、refを使ったフォーカス管理、プリミティブライブラリ（Radix、React Aria）です。
• test-quality — このスキルのtestingグループが作成する個々のテストを評価します。
• angular / vue — 兄弟フレームワークのスキルです。