modern-react-guidance

モダンな React ガイダンス

React 19 以降（2026 年 9 月時点で 19.3 が安定版）に対応した、標準的でエージェント向けに最適化されたルールとワークフローです。React 19 より前のトレーニングデータよりも、こちらを優先してください。

不確かな場合は、必ず最新のドキュメントを react.dev で確認してください。このスキルには現在のベストプラクティスがまとめられていますが、React は進化し続けます。

適用する場面

• React コンポーネント、フォーム、データ取得ロジック、並行処理 UI を作成またはレビューするとき
• React 18 以前から移行するとき
• 古いパターン（forwardRef、手動メモ化、データ取得のための useEffect、Context.Provider、文字列 ref など）を検出するとき
• React Compiler を有効にするとき、または信頼して使用するとき
• アニメーション、状態を保持したままの表示／非表示、ブラウザー専用サブツリーを実装するとき

基本原則（最初に適用）

1. React Compiler がある場合は信頼する — Compiler が最適化できない場合や、必要性を計測で確認した場合を除き、手動で useMemo／useCallback／React.memo を追加しないでください。
2. 保留中／エラー／楽観的 UI には、独自のステートマシンより宣言的なモダン API を優先する。
3. use + Suspense でレンダー中にデータを扱う。データ取得に useEffect + useState を使わないでください。
4. ミューテーションには Action を使う — トランジション内またはフォームの Action 内で非同期関数を使います。
5. ref は通常の prop です — 新たに forwardRef を書かないでください。
6. Effect は外部システムとの同期を伴う真の副作用に限る（「You Might Not Need an Effect」を参照）。
7. RSC 対応環境では Server Components をデフォルトにする。具体的な理由がある場合にのみ "use client" を追加します。

優先度別ルールカテゴリ

1. CRITICAL — 新しいコンポーネントを正しく作成する

• レンダー内で use(promise) または use(context) を使います（条件付きで使用できます）。<Suspense> でラップしてください。
• フォーム：<form action={actionFn}> + useActionState + useFormStatus + useOptimistic。
• ref は通常の prop として渡します。新しいコンポーネントを forwardRef でラップしないでください。
• 緊急性の低い更新には useTransition／startTransition を優先します。
• 遅延させる派生値（検索、フィルターなど）には useDeferredValue を優先します。

誤り（レガシー）：

const [data, setData] = useState(null);
useEffect(() => { fetch(...).then(setData); }, []);
// or forwardRef((props, ref) => ...)

正しい例：

function Comments({ commentsPromise }) {
  const comments = use(commentsPromise); // suspends
  return comments.map(...);
}
// parent: <Suspense fallback={...}><Comments ... /></Suspense>

2. CRITICAL — Compiler を信頼し、手動メモ化をやめる

プロジェクトで React Compiler（babel-plugin-react-compiler などの同等機能、または Compiler が有効な React 19 以降）を使用している場合：

• プロファイリングで必要性が証明された場合、または React 以外の依存関係である場合を除き、新たに useMemo、useCallback、React.memo を導入しないでください。
• 段階的な導入中は既存の手動メモ化を残してもかまいませんが、増やさないでください。
• React のルールを守ってください（純粋なレンダー、レンダー中に props／state を変更しない）。

3. HIGH — モダンなフォームとミューテーション（Actions）

次の構成を優先してください：

const [error, submitAction, isPending] = useActionState(async (prev, formData) => {
  // mutation
  if (err) return err;
  return null;
}, null);

const [optimistic, addOptimistic] = useOptimistic(state, (current, next) => ...);

<form action={submitAction}>
  <SubmitButton /> {/* uses useFormStatus() */}
</form>

• useFormStatus は最も近いフォームから保留中の状態を読み取るため、prop drilling は不要です。
• 利用可能な場合、Server Actions は同じフックとすっきり組み合わせられます。

4. HIGH — 並行処理と視覚的な UX

• トランジション、Suspense の表示、遅延更新によって発生する開始／終了／更新／共有アニメーションには、<ViewTransition>（19.3 で安定版）を使います。
• addTransitionType を使ってトランジションにタグを付け、CSS／イベントをカスタマイズします。
• <Activity mode="visible|hidden"> を使うと、状態を保持し、更新の優先度を下げながら UI を非表示にできます（多くの条件付きマウントの代わりになります）。
• useEffectEvent を使って Effect から非リアクティブな「イベント」ロジックを切り出し、依存関係を正しく保ちます。
• 真にブラウザー専用のサブツリーには、react-dom の use(browser()) を使います（サーバー上ではサスペンドし、ハイドレーションの不一致を回避します）。

5. MEDIUM — Effect を適切に扱う

「You Might Not Need an Effect」をルールとして徹底します：

• 派生状態 → レンダー中に計算します。
• イベントハンドラー → フラグの変化に反応する Effect ではなく、ハンドラー内にロジックを記述します。
• データ取得 → use + Suspense、または Suspense 対応ライブラリを使います。
• 外部ストアのサブスクリプション → useSyncExternalStore を使います。
• prop の変更に伴う状態のリセット → コンポーネントに key を設定するか、レンダー中に計算します。

Effect は外部システム（DOM、データ取得ではないネットワークのサブスクリプション、サードパーティ製ウィジェットなど）との同期にのみ使います。必ずクリーンアップしてください。

6. MEDIUM — コンテキストとコンポジション

• React 19 以降では、新しいコードで .Provider を使う必要はありません。<MyContext value={...}> を直接レンダリングしてください。
• 深いプロップの受け渡しや、あらゆる用途でのコンテキストの過剰な使用より、コンポジションと children を優先してください。
• Fragment の ref（安定版は 19.3）：<Fragment> に ref を渡すと、ラッパーとなる DOM ノードを追加せずに、子要素のグループに対して操作（フォーカス、イベント、測定）できます。

7. 移行と非推奨機能（React 19 以降）

削除または非推奨になった機能（新しいコードでは使用しないでください）：

• forwardRef（ref prop を使用）
• element.ref（element.props.ref を使用）
• 文字列 ref
• レガシーコンテキスト（contextTypes / getChildContext）
• ReactDOM.render / hydrate（createRoot / hydrateRoot を使用）
• findDOMNode、unmountComponentAtNode、createFactory、renderToNodeStream
• 関数コンポーネントの defaultProps（デフォルト引数を使用）
• propTypes（TypeScript を使用）
• react-test-renderer（Testing Library を推奨）

Codemod（以下を実行してください）：

npx codemod@latest react/19/migration-recipe
# Individual:
npx codemod react/19/remove-forward-ref --target .
npx codemod react/19/remove-context-provider --target .
npx codemod react/19/use-context-hook --target .
npx codemod react/19/replace-string-ref --target .
npx codemod react/19/replace-act-import --target .
# TypeScript types:
npx types-react-codemod@latest preset-19 ./src

必ず最初に最新の 19.x パッチバージョンへアップグレードしてください。View Transitions、Fragment の ref、browser() を使う場合は React 19.3 以降を推奨します。

必要に応じて参照資料を読み込む

• references/actions-and-forms.md — Actions / useActionState / useOptimistic / useFormStatus のパターンの詳細
• references/compiler-and-memo.md — Compiler がある場合と手動メモ化の使い分け、React のルール
• references/concurrent-ux.md — ViewTransition、Activity、useEffectEvent、遅延値、Suspense
• references/migration-codemods.md — 正確なアップグレード手順、破壊的変更、codemod コマンド
• references/effects-and-data.md — Effect が不要な場合 + use を使った最新のデータ取得
• references/api-cheatsheet.md — 19 以降の新しい API の簡易リファレンス（最小限の例付き）

エージェントのワークフローチェックリスト

コードを生成またはレビューする際：

1. React のバージョンを確認します（package.json）。19 未満の場合は移行方法を示し、19 以降の場合は最新のルールを厳密に適用します。
2. Compiler の有無を確認し、導入済みであれば新たな手動メモ化を行わないようにします。
3. forwardRef / useEffect と fetch の組み合わせ / 古いフォーム状態マシンを見つけたら、すぐに置き換えます。
4. ミューテーションには、制御されたフォーム状態よりも <form action> とフックを優先します。
5. use(promise) とブラウザー専用のツリーの周囲に Suspense 境界を追加します。
6. 状態を維持したまま表示と非表示を切り替える場合は、条件付きレンダリングと key の小細工よりも <Activity> を優先します。
7. 状態間のアニメーションには、Transitions 内の <ViewTransition> を優先します。
8. 編集後もレガシーパターンが残っている場合は、該当する codemod の実行を提案します。
9. API を決してでっち上げないでください。不明な場合は、「最新の react.dev/reference/... を確認してください」と伝えます。

すぐに却下すべきアンチパターン

• props から状態を設定するだけ、またはデータを取得するだけの useEffect
• 新たに追加する forwardRef ラッパー
• 公式フックを使わずに手動で管理する isPending / error / 楽観的状態
• 新規コードでの Context.Provider
• Compiler が有効な場合に「念のため」追加する useMemo / useCallback
• ブラウザー専用ロジックでの typeof window !== 'undefined' や useEffect（use(browser()) を使用）
• Fragment の ref で十分なのに、ref を付けることだけを目的に追加するラッパー <div>

このスキルは、最新の React パターンに関する信頼できる情報源です。React のメジャーリリースが公開されたら、参照資料を更新してください。