vercel-react-best-practices

Vercel React のベストプラクティス

Vercel のルールをもとにした、リポジトリで管理されている React および Next.js のガイダンスです。列挙されたすべてのパターンをアプリケーション全体に適用するのではなく、依頼された作業における具体的なパフォーマンス上の仕組みに対処するために使用してください。

最適化の前に関連性を確認する

影響を受けるパス、現実的な負荷、回避可能なコストを特定してください。たとえば、依存関係によるウォーターフォール、リクエストの繰り返し、過剰なバンドル、コストの高いレンダリング、頻繁に実行される計算などです。その仕組みを裏付けるコードと使用状況の証拠、または代表的なトレース／プロファイルを確認してください。ルールに該当することや影響度ラベルだけでは、変更の根拠になりません。

ユーザーの作業範囲、既存のアーキテクチャ、正確性に関する契約を維持してください。ライブラリ、キャッシュ、抽象化を追加する前に、既存の機能やコードへの直接的な変更を優先してください。提案する最適化に見込まれる意味のある効果がない場合は、すでに十分なコードを変更しないでください。正確性とセキュリティ上の要件を満たすために、パフォーマンス向上の証明は必要ありません。

パフォーマンス上の効果を主張する場合は、同等の負荷と条件で変更前後を測定してください。測定できない場合は、裏付けのある仕組みを説明し、その効果が期待値または未検証であることを明記してください。サンプルの実行時間、割合、影響度評価を、ユーザーのアプリケーションで測定した結果として扱わないでください。

依存関係とキャッシュの所有者

SWR、better-all、LRU キャッシュ、メモ化は、条件に応じて選択するものです。プロジェクトのデータ取得、スケジューリング、キャッシュ機能が要件を満たす場合は、それらを再利用してください。依存関係を追加するのは、実証された要件によって保守コストと実行時コストが正当化される場合に限ります。インポート例は、インストールの指示ではありません。

キャッシュを追加する前に、処理が繰り返されること、適切なキーの同一性、所有者と有効期間、許容可能な古さ、無効化、メモリ上限、データに必要なユーザーまたはテナントの分離を確認してください。役に立つ範囲で最小のスコープを選択してください。これらの契約を維持できない場合は、変更可能な結果や認可に依存する結果をキャッシュしないでください。

適用する場面

以下の場合に、これらのガイドラインを参照してください。

• 新しい React コンポーネントまたは Next.js ページを作成するとき
• データ取得を実装するとき（クライアント側またはサーバー側）
• パフォーマンス上の問題についてコードをレビューするとき
• 既存の React／Next.js コードをリファクタリングするとき
• バンドルサイズや読み込み時間を最適化するとき

優先度別のルールカテゴリ

これらの評価は、該当する条件下で調査する優先度を相対的に示すものです。ルールに記載された数値上の向上は例示または特定の情報源に基づくものであり、保証や現在のアプリケーションでの測定結果ではありません。レビューでは、ルールの評価をそのまま当てはめず、実証された影響に基づいて深刻度を評価してください。

優先度	カテゴリ	影響	プレフィックス
1	ウォーターフォールの解消	重大	async-
2	バンドルサイズの最適化	重大	bundle-
3	サーバー側のパフォーマンス	高	server-
4	クライアント側のデータ取得	中〜高	client-
5	再レンダリングの最適化	中	rerender-
6	レンダリングのパフォーマンス	中	rendering-
7	JavaScript のパフォーマンス	低〜中	js-
8	高度なパターン	低	advanced-

クイックリファレンス

1. ウォーターフォールの解消（重大）

• async-cheap-condition-before-await - フラグやリモート値を待機する前に、コストの低い同期条件を確認する
• async-defer-await - 実際に使用する分岐の中に await を移動する
• async-parallel - 独立した処理には Promise.all() を使用する
• async-dependencies - 実際の依存関係を直接表現する。導入する価値がある場合は better-all を検討する
• async-api-routes - API ルートではプロミスを早めに開始し、待機を遅らせる
• async-suspense-boundaries - Suspense を使用してコンテンツをストリーミングする

2. バンドルサイズの最適化（CRITICAL）

• bundle-barrel-imports - バレルファイルを避け、直接インポートします
• bundle-analyzable-paths - 大規模なバンドルやトレースを避けるため、静的に解析可能なインポートパスとファイルシステムパスを優先します
• bundle-dynamic-imports - 大きなコンポーネントには next/dynamic を使用します
• bundle-defer-third-party - アナリティクスやロギングはハイドレーション後に読み込みます
• bundle-conditional - 機能が有効になった場合にのみモジュールを読み込みます
• bundle-preload - 体感速度を高めるため、ホバー／フォーカス時にプリロードします

3. サーバーサイドのパフォーマンス（HIGH）

• server-auth-actions - API ルートと同様に、サーバーアクションを認証します
• server-cache-react - サポート対象のサーバーレンダリング内で作業が繰り返される場合は、React.cache() の利用を検討します
• server-cache-lru - 鮮度と分離の要件を満たして再利用できる場合は、リクエストをまたぐ有界キャッシュの利用を検討します
• server-dedup-props - RSC の props における重複したシリアライズを避けます
• server-hoist-static-io - 静的な I/O（フォント、ロゴ）をモジュールレベルに引き上げます
• server-no-shared-module-state - RSC／SSR でリクエストごとに変化する状態をモジュールレベルで共有しないようにします
• server-serialization - クライアントコンポーネントに渡すデータを最小限にします
• server-parallel-fetching - コンポーネントを再構成して、フェッチを並列化します
• server-parallel-nested-fetching - Promise.all 内で項目ごとのネストされたフェッチを連鎖させます
• server-after-nonblocking - ブロックしない処理には after() を使用します

4. クライアントサイドのデータフェッチ（MEDIUM-HIGH）

• client-swr-dedup - リクエストの重複排除を再利用し、プロジェクトのデータレイヤーに適している場合は SWR の利用を検討します
• client-event-listeners - グローバルイベントリスナーの重複を排除します
• client-passive-event-listeners - スクロールにはパッシブリスナーを使用します
• client-localstorage-schema - localStorage のデータをバージョン管理し、最小限にします

5. 再レンダリングの最適化（MEDIUM）

• rerender-defer-reads - コールバック内でのみ使用する状態を購読しないようにします
• rerender-memo - コストの高い処理をメモ化したコンポーネントに切り出します
• rerender-memo-with-default-value - プリミティブでないデフォルトの props をコンポーネントの外に定義します
• rerender-dependencies - エフェクトではプリミティブな依存値を使用します
• rerender-derived-state - 生の値ではなく、派生した真偽値を購読します
• rerender-derived-state-no-effect - エフェクトではなく、レンダリング中に状態を導出します
• rerender-functional-setstate - コールバックを安定させるため、関数形式の setState を使用します
• rerender-lazy-state-init - コストの高い値には useState に関数を渡します
• rerender-simple-expression-in-memo - 単純なプリミティブ値にはメモ化を使わないようにします
• rerender-split-combined-hooks - 依存関係が独立したフックを分割します
• rerender-move-effect-to-event - インタラクションのロジックをイベントハンドラーに記述します
• rerender-transitions - 緊急性の低い更新には startTransition を使用します
• rerender-use-deferred-value - 入力への応答性を保つため、コストの高いレンダリングを遅延させます
• rerender-use-ref-transient-values - 頻繁に変わる一時的な値には ref を使用します
• rerender-no-inline-components - コンポーネント内でコンポーネントを定義しないようにします

6. レンダリングのパフォーマンス（MEDIUM）

• rendering-animate-svg-wrapper - SVG 要素ではなく div ラッパーをアニメーションさせます
• rendering-content-visibility - 長いリストには content-visibility を使用します
• rendering-hoist-jsx - 静的な JSX をコンポーネントの外に切り出します
• rendering-svg-precision - SVG の座標精度を下げます
• rendering-hydration-no-flicker - クライアントのみのデータにはインラインスクリプトを使用します
• rendering-hydration-suppress-warning - 想定される不一致の警告を抑制します
• rendering-activity - 表示／非表示には Activity コンポーネントを使用します
• rendering-conditional-render - 条件が 0、NaN、またはレンダリングされる別の偽値になる可能性がある場合は、&& の代わりに三項演算子を使用します
• rendering-usetransition-loading - ローディング状態には useTransition を優先します
• rendering-resource-hints - プリロードには React DOM のリソースヒントを使用します
• rendering-script-defer-async - script タグに defer または async を指定します

7. JavaScript のパフォーマンス（低〜中）

• js-batch-dom-css - レイアウトの読み取りとスタイルの書き込みを分けます。連続する書き込みはすでにバッチ処理されています
• js-index-maps - 繰り返し検索する場合は Map を構築します
• js-cache-property-access - ループ内ではオブジェクトのプロパティをキャッシュします
• js-cache-function-results - 適切なキーと有効期間を設定できる場合に限り、コストの高い繰り返し計算をキャッシュします
• js-cache-storage - 信頼できる無効化ポリシーがある場合に限り、頻繁に読み取るストレージをキャッシュします
• js-combine-iterations - 複数の filter/map を 1 つのループにまとめます
• js-length-check-first - コストの高い比較の前に配列の長さを確認します
• js-early-exit - 関数から早期に return します
• js-hoist-regexp - RegExp の作成をループの外に移動します
• js-min-max-loop - 最小値／最大値を求める際は sort ではなくループを使用します
• js-set-map-lookups - O(1) の検索には Set/Map を使用します
• js-tosorted-immutable - 不変性を保つには toSorted() を使用します
• js-flatmap-filter - 1 回の処理でマッピングとフィルタリングを行うには flatMap を使用します
• js-request-idle-callback - 重要度の低い処理をブラウザーのアイドル時間に遅延させます

8. 高度なパターン（低）

• advanced-effect-event-deps - useEffectEvent の結果を effect の依存関係に含めないでください
• advanced-event-handler-refs - イベントハンドラーを ref に保存します
• advanced-init-once - アプリの読み込みごとに 1 回だけアプリを初期化します
• advanced-use-latest - 安定したコールバック参照には useLatest を使用します

使用方法

インデックスを使って、特定したメカニズムに関連するルールを選びます。該当する個別ファイルと適用可能な例を読み、具体的な依存関係や未解決の疑問がある場合に限って追加のルールを読み込みます。コンパイル済みガイド全体をデフォルトで読む必要はありません。

rules/async-parallel.md
rules/bundle-barrel-imports.md

例のラベルは、記載されたワークロードと前提条件に照らして解釈してください。例を適用する際は、フレームワーク／バージョンとの互換性、および実際のエラー、順序、キャッシュ、所有権に関する契約を維持してください。

コンパイル済みリファレンス

rules/ には正式なガイダンスが含まれています。AGENTS.md は意図的にガイド全体を読むためのコンパイル済みリファレンスであり、実行時のエントリーポイントではありません。ルールを保守する場合は、コンパイル済みのセクションと、影響を受けるインデックスまたはメタデータを同じ変更内で同期してください。保守の詳細については、このスキルの README.md を参照してください。