react-refactor

React のリファクタリングのベストプラクティス

React アプリケーションのアーキテクチャをリファクタリングするためのガイドです。7 つのカテゴリにわたる 40 のルールを収録し、影響度の高いもの（コンポーネントと状態のアーキテクチャ）から段階的に適用するもの（リファクタリングの安全性）まで、優先度順に並べています。

適用するタイミング

• 既存の React コードベースをリファクタリングするときや、大規模な再構成を計画するとき
• PR をレビューし、アーキテクチャ上の問題やコードのにおいを確認するとき
• 巨大なコンポーネントを、役割を絞った単位に分割するとき
• コンポーネントのロジックから再利用可能なフックを抽出するとき
• React コードのテスト容易性を高めるとき
• 機能モジュール間の結合を減らすとき

ルールのカテゴリ

カテゴリ	影響度	ルール数	主なトピック
コンポーネントアーキテクチャ	CRITICAL	8	複合コンポーネント、ヘッドレスパターン、props よりコンポジション、クライアント境界
状態アーキテクチャ	CRITICAL	7	状態のコロケーション、状態マシン、URL の状態、導出値
フックのパターン	HIGH	6	単一責任、命名、依存関係の安定性、コンポジション
コンポーネントの分割	HIGH	6	スクロールテスト、変更理由に基づく抽出、ビューとロジックの分離
結合と凝集	MEDIUM	4	依存性注入、循環依存、安定したインポート、バレルファイルを使わない
データと副作用	MEDIUM	4	サーバー優先のデータ取得、TanStack Query、エラーバウンダリ
リファクタリングの安全性	LOW-MEDIUM	5	特性化テスト、振る舞いのテスト、統合テスト

クイックリファレンス

重要なパターン — まずこれらを正しく適用します。

• props が増えすぎる場合は、複合コンポーネントを使います
• 状態は、それを使うコンポーネントの近くに置きます
• 複雑な UI ワークフローには状態マシンを使います
• コンテナのロジックと表示コンポーネントを分離します

よくある間違い — 次のアンチパターンは避けます。

• 状態を読み取るコンポーネントが 1 つだけなのに、状態を App まで持ち上げる
• 頻繁に変化する値にコンテキストを使う
• データ取得、変換、キャッシュをすべて行う単一の巨大なフック
• 振る舞いではなく実装の詳細をテストする

目次

1. コンポーネントアーキテクチャ — CRITICAL
   • 1.1 コンポーネントの Props にインターフェース分離を適用する — CRITICAL（不要な再レンダリングを30～50％防止します）
   • 1.2 種類ではなく機能ごとにファイルをまとめる — CRITICAL（ディレクトリ間の移動を70％削減します）
   • 1.3 Render Props をカスタムフックに変換する — CRITICAL（ネストを2～4階層解消します）
   • 1.4 ロジックを再利用するためにヘッドレスコンポーネントを抽出する — CRITICAL（再利用できる場面が5倍になります）
   • 1.5 Props の増えすぎを避け、コンポジションを優先する — CRITICAL（Props の数を50～70％削減します）
   • 1.6 コンテナロジックとプレゼンテーションコンポーネントを分離する — CRITICAL（独立したテストが可能になります）
   • 1.7 暗黙的な状態共有には複合コンポーネントを使う — CRITICAL（API の範囲を60％縮小します）
   • 1.8 クライアント境界をリーフコンポーネントに寄せる — HIGH（60～80％をサーバーでレンダリングできます）
2. 状態アーキテクチャ — CRITICAL
   • 2.1 状態を使用するコンポーネントの近くに配置する — CRITICAL（Props の受け渡しを60％削減します）
   • 2.2 状態を同期せず、値を導出する — CRITICAL（2回レンダリングされるサイクルを解消します）
   • 2.3 複数のコンポーネントが状態を読み取る場合にのみ状態を持ち上げる — CRITICAL（不要な親コンポーネントの再レンダリングを解消します）
   • 2.4 変更頻度の低い値にのみ Context を使う — CRITICAL（再レンダリングを5～50分の1に削減します）
   • 2.5 複雑な UI ワークフローにはステートマシンを使う — CRITICAL（有効な状態の数を2^nからNに削減します）
   • 2.6 共有可能なビューの状態には URL パラメーターを使う — CRITICAL（ディープリンクと共有が可能になります）
   • 2.7 複数フィールドの状態遷移には useReducer を使う — CRITICAL（起こり得ない状態を解消します）
3. フックのパターン — HIGH
   • 3.1 カスタムフックでオブジェクトや配列を依存関係にしない — HIGH（レンダリングのたびにエフェクトが再実行されるのを防ぎます）
   • 3.2 フックをネストせず、組み合わせて使う — HIGH（依存関係グラフをフラットにします）
   • 3.3 名前を付けられる動作はカスタムフックに抽出する — HIGH（コンポーネントを40～60％短くできます）
   • 3.4 見つけやすさのため、フックの命名規則に従う — HIGH（検索にかかる時間を40％削減します）
   • 3.5 カスタムフックは単一の責務に保つ — HIGH（テストが3倍容易になります）
   • 3.6 Refs とコールバックでフックの依存関係を安定させる — HIGH（無限ループを防ぎます）
4. コンポーネントの分割 — HIGH
   • 4.1 スクロールテストで大きすぎるコンポーネントを特定する — HIGH（コードレビューが3倍速くなります）
   • 4.2 中途半端にせず、コンポーネントの抽出を完了させる — HIGH（独立したテストと再利用が可能になります）
   • 4.3 独立した変更理由ごとにコンポーネントを抽出する — HIGH（変更ごとに編集するファイルを70％削減します）
   • 4.4 コンポーネント本体から純粋関数を抽出する — HIGH（単体テストを10倍速く実行できます）
   • 4.5 早すぎる抽象化をインライン化してから再抽出する — HIGH（コードを40～60％簡潔にします）
   • 4.6 ビュー層とビジネスロジックを分離する — HIGH（テストスイートを5倍速く実行できます）
5. 結合度と凝集度 — MEDIUM
   • 5.1 中間モジュールで循環依存を解消する — MEDIUM（インポート時に値が未定義になるバグを解消します）
   • 5.2 安定した公開 API のみからインポートする — MEDIUM（内部のリファクタリングが可能になります）
   • 5.3 依存関係を整理するため、バレルファイルを使わない機能モジュールを使う — MEDIUM（ビルド時間を200～800ミリ秒短縮します）
   • 5.4 外部サービスには依存性注入を使う — MEDIUM（テストのセットアップを3倍速くできます）
6. データと副作用 — MEDIUM
   • 6.1 デフォルトではサーバーでデータを取得する — MEDIUM（クライアント JS を30～60％削減します）
   • 6.2 データ取得の粒度に合わせてエラーバウンダリーを配置する — MEDIUM（エラーを該当セクション内に隔離します）
   • 6.3 アクションを近くに配置するには Context Module パターンを使う — MEDIUM（データの変更処理を一元化します）
   • 6.4 クライアント側のサーバー状態には TanStack Query を使う — MEDIUM（データ取得の定型コードを80％削減します）
7. 安全なリファクタリング — LOW-MEDIUM
   • 7.1 リファクタリングしたコンポーネントにスナップショットテストを使わない — LOW-MEDIUM（誤検知によるテスト失敗を解消します）
   • 7.2 テスト容易性を高めるために純粋関数を抽出する — LOW-MEDIUM（テストの実行を10倍速くできます）
   • 7.3 コンポーネントの検証には単体テストより統合テストを優先する — LOW-MEDIUM（バグを40％多く検出します）
   • 7.4 実装の詳細ではなく、コンポーネントの動作をテストする — LOW-MEDIUM（テストの更新を5分の1に削減します）
   • 7.5 リファクタリング前に特性テストを作成する — LOW-MEDIUM（意図しない変更の90％を検出します）

参考資料

1. https://react.dev
2. https://react.dev/learn/thinking-in-react
3. https://kentcdodds.com/blog/application-state-management-with-react
4. https://testing-library.com/docs/guiding-principles
5. https://patterns.dev

関連スキル

• React 19 API のベストプラクティスについては、react スキルを参照してください
• アプリケーションのパフォーマンス最適化については、react-optimise スキルを参照してください
• クライアントサイドのフォーム処理については、react-hook-form スキルを参照してください