react-best-practices

React のベストプラクティス

概要

React のパフォーマンスと品質に関するルーティングおよび優先度のガイドです。9 つのカテゴリにわたる 27 のルールが含まれています。ルールファイルには、詳しい解説、例、コードレビューで注意すべき点、影響度の指標が記載されています。

適用するタイミング

次のような場合に、これらのガイドラインを参照してください。

• 新しい React コンポーネントを作成する
• データ取得を実装する
• パフォーマンスの問題がないかコードをレビューする
• 既存の React コードをリファクタリングする
• バンドルサイズや読み込み時間を最適化する

優先度順のガイドライン

ルールは影響度に基づいて優先順位が付けられています。

優先度	カテゴリ	影響度
1	ウォーターフォールの解消	CRITICAL
2	バンドルサイズの最適化	CRITICAL
3	クライアントサイドのデータ取得	MEDIUM-HIGH
4	再レンダリングの最適化	MEDIUM
5	レンダリングパフォーマンス	MEDIUM
6	JavaScript のパフォーマンス	LOW-MEDIUM
7	コンポーネント構造	MEDIUM-HIGH（保守性）
8	テスト	MEDIUM-HIGH（正確性）
9	型安全性	HIGH

クイックリファレンス

重要なパターン（最優先で適用）

ウォーターフォールを解消する：

• 独立した非同期処理には Promise.all() を使用します（async-parallel）

バンドルサイズを削減する：

• バレルファイルからのインポートを避け、ソースから直接インポートします（bundle-barrel-imports）
• 重要度の低いサードパーティライブラリの読み込みを遅らせます（bundle-defer-third-party）

中程度の影響を与えるパターン

クライアント側のデータ取得：

• Tanstack Query を使用してリクエストを自動的に重複排除します（client-request-dedupe）
• 依存するクエリパラメーターの値は値そのものか undefined にします。| null や偽のフォールバック値は使いません。呼び出し元で型を絞り込んでフックを厳密に保つか、フックがオプションのパラメーターを受け取る必要がある場合は skipToken でガードします（client-request-dedupe）

再レンダーの最適化：

• コストの高い値には遅延状態初期化を使用します（rerender-lazy-state-init）
• 緊急性の低い更新には startTransition を適用します（rerender-transitions）
• UI ハンドラーはシンプルに保ち、エフェクトから呼び出されるロジックにのみ Effect Events を使用します（rerender-useeffect-function-calls）
• useEffect で状態をリセットしません。判別子を親に持ち上げ、分岐を再マウントします（rerender-no-useeffect-state-reset）
• useMemo や useCallback は追加しません。メモ化の判断は、プロファイラーの根拠を持つ開発者に委ねます（rerender-no-usememo-usecallback）
• レンダリング中や useEffect 内で setState を呼び出しません。レンダリング中に値を導出するか、中間コンポーネントに状態の所有権を移します（rerender-no-setstate-in-render-or-effect）

コンポーネントの構成：

• ファイルごとにドメインコンポーネントまたはフックを1つ配置し、それぞれの責務を1つにします。肥大化したコンポーネントは分割します（structure-single-responsibility）
• コンポーネント、フック、関数、ユーティリティの API は範囲を絞ります。大きすぎる props、引数、戻り値オブジェクトは、コンポーネントレベルで組み合わせる目的別の単位に分割します。同じ値を1つのオブジェクトにまとめても解決にはなりません（structure-narrow-apis）
• JSX を返すヘルパーには PascalCase のコンポーネント名を使用し、JSX 以外の値を扱うヘルパーには小文字の名前を使用します（structure-component-naming）
• 別の引数から計算できる値は受け取らず、props やパラメーターを導出します（structure-derive-dont-duplicate）
• 複雑な導出ロジックは、名前付きローカル変数と述語、または早期リターンを使う純粋なヘルパーに切り出します。過大な条件式、ネストされた三項演算子、選択ではなく計算を行う三項演算子（複数行の分岐、または条件で確認した内容を再アサートする as キャスト）、フォールバックの連鎖、let によるレンダリング準備はコードのにおいです。これはレンダリング準備だけでなく、フックのオプション、リクエストビルダー、設定マップ、リデューサーにも当てはまります（structure-complex-derived-logic）
• 早期の if ガードでビューを選択しつつ、レイアウトのラッパーは1か所にまとめます。ボディコンポーネントを分岐させ、シェルを三項演算子で選択したり重複させたりしません（structure-early-return-render-branches）
• 項目の集合が固定されている場合は、各項目に対して明示的な props を持ち、データとローディング状態を管理するコンポーネントを1つずつ作成します。設定オブジェクトの配列をコンポーネントの形にマッピングしません（structure-composition-over-config）
• ドメインコンポーネントがデータを取得する場合は、スロットを配置する純粋なレイアウトコンポーネントを通じてレンダリングし、スロットの内容をスケルトンと解決済みのサブドメインコンポーネントの間で分岐させます（structure-data-fetching-layout）

テスト：

• 実際の @mastra/client-js と React Query のスタックを使い、ネットワークのみをモックする BDD テストにします。独自のフック、サービス、認証ゲーティング、SDK を vi.mock でモックしません（testing-bdd-no-mocks）
• 見た目の動作を検証するためにクラス名をアサートすることは避けます。計算済みスタイル、ユーザーから見える動作、ブラウザーでの検証を優先し、クラス名だけを実装に合わせて確認するテストより、テストを作らないことを優先します（testing-no-classname-assertions）

型安全性：

• 本番コードでもテストでも、as による型アサーションは一切使いません。実際の型ガード、クエリのジェネリクス（querySelector<T>、getByRole<T>）、型付きフィクスチャーファクトリー、またはモックの implements で型を絞り込みます。許可される形式は as const のみです。キャストを、typeof value === 'object' だけを確認するドメイン型述語に置き換えてはいけません。その場合は isRecord ヘルパーと呼ぶか、使用するフィールドを検証します（types-no-type-assertions）
• 値がない場合は null ではなく undefined とオプションの ? を使用します。外部の null は境界で変換し、呼び出し元が値の不在とフォールバックのレンダリングを担うよう、末端の props は厳密に保ちます（types-no-null）

レンダリングパターン

• SVG 要素を直接ではなく、SVG ラッパーをアニメーションさせます（rendering-animate-svg-wrapper）
• 長いリストには content-visibility: auto を使用します（rendering-content-visibility）

JavaScript パターン

• 繰り返し検索には Set/Map を使用します（js-set-map-lookups）
• 不変性を保つため、sort() ではなく toSorted() を使用します（js-tosorted-immutable）
• 配列を比較する際は、最初に長さを確認します（js-length-check-first）

参考資料

ルールファイルは、詳細なガイダンスと例を示す標準の情報源です。

• references/react-best-practices-reference.md - カテゴリー順とルールファイルのパスを含むルールカタログ
• references/rules/ - カテゴリー別に整理された、標準の個別ルールファイル

特定のパターンを実装またはレビューする際は、関連するルールファイルのみを読み込んでください。すべての例を読み込まずに、カタログを使って適切なルールを選びます。

特定のパターンを検索するには、rules ディレクトリで grep を実行します。

grep -l "Promise.all" references/rules/
grep -l "barrel" references/rules/
grep -l "Tanstack" references/rules/

references/rules/ のルールカテゴリー

• async-* - ウォーターフォールの解消（1 ルール）
• bundle-* - バンドルサイズの最適化（2 ルール）
• client-* - クライアント側のデータ取得（1 ルール）
• rerender-* - 再レンダリングの最適化（6 ルール）
• rendering-* - DOM レンダリングのパフォーマンス（2 ルール）
• js-* - JavaScript のマイクロ最適化（3 ルール）
• types-* - 型安全性／as キャストなし、null なしのルール（2 ルール）
• structure-* - コンポーネント／フック／関数／ユーティリティの構成（8 ルール）
• testing-* - BDD テスト＋ネットワークのみをモックする方針＋className 実装ミラーアサーションなし（2 ルール）