accelint-react-best-practices

React のベストプラクティス

React アプリケーションの包括的なパフォーマンス最適化とベストプラクティスです。React コードを扱う AI エージェントや LLM 向けに設計されています。

React で絶対に避けること

これらは、実際の本番環境で問題を引き起こす最も重大なアンチパターンです。専門家は、デバッグやパフォーマンス調査を通じて、苦労してこれらの教訓を学びました。

コンポーネント内でコンポーネントを定義しないでください — レンダリングのたびに新しいコンポーネント型が作られ、状態が失われて DOM が再作成される全面的な再マウントを引き起こします。その結果、キー入力のたびに入力フィールドのフォーカスが失われたり、アニメーションが予期せず再開したり、親コンポーネントのレンダリングごとに useEffect のクリーンアップとセットアップが実行されたりします。

コールバック内で読み取るだけなら、searchParams/localStorage をサブスクライブしないでください — コンポーネントがその値を表示していなくても、URL の変更やストレージイベントのたびに再レンダリングされます。代わりに、コールバック内で直接読み取ります：new URLSearchParams(window.location.search)。

useEffect の依存配列にオブジェクトや配列を使わないでください — オブジェクトは毎回新しい参照で再作成されるため、レンダリングのたびにエフェクトが実行されます。オブジェクトからプリミティブ値（id、name）を取り出し、代わりにそれらを依存配列に指定します。

useState + useEffect で派生状態を同期しないでください — 余分な再レンダリング、無限ループ、古い中間状態につながります。代わりに、レンダリング中に派生値を計算します：const fullName = firstName + ' ' + lastName。

クライアントのみの状態（localStorage、cookies、デバイス検出）を SSR コンポーネントで直接使用しないでください — サーバーの HTML とクライアントのレンダリングが一致しないハイドレーションの不一致が起こり、React の警告、表示のちらつき、インタラクティブ機能の不具合につながります。React がハイドレーションする前に、同期的なインラインの <script> を使います。

React 19 以降では forwardRef を使わないでください — 非推奨の API です。代わりに、ref を通常のプロパティとして使います：function MyInput({ ref }) { return <input ref={ref} /> }。

メモ化されたコンポーネントのプロパティとして、コールバック／オブジェクト／配列をインラインで作成しないでください — レンダリングのたびに新しい参照が作られるため、メモ化が機能しなくなります。モジュールスコープに切り出すか、useMemo または useCallback を使います：const config = useMemo(() => ({ theme }), [theme])。

ユーザー操作のロジックを useEffect に入れないでください — ボタンクリックやフォーム送信で実行される処理なら、イベントハンドラーに直接記述します。エフェクトは外部システムとの同期に使うものであり、ユーザー操作によって実行する処理に使うものではありません。

パフォーマンスを最適化する前に確認すること

memo／useMemo／useCallback による最適化を提案する前に、それらが必要かどうかを判断します。

1. このプロジェクトでは React Compiler を使っていますか？

   • package.json／設定ファイルで babel-plugin-react-compiler または react-compiler-webpack-plugin を検索します
   • 使っている場合 → 手動のメモ化（memo、useMemo、useCallback、静的 JSX の巻き上げ）は省略します。コンパイラーがこれらを自動的に処理します
   • 使っていない場合 → このスキルにある関連する最適化をすべて適用します
   • コンパイラーが処理する内容については、react-compiler-guide.md を参照してください

2. これは本当にパフォーマンスの問題ですか？

   • ユーザーは計測やプロファイリングを行い、ボトルネックを特定していますか？
   • それとも、全般的なレビュー／最適化を求めていますか？

3. 規模はどのくらいですか？

   • リストの場合：項目はいくつありますか？（content-visibility と仮想化のどちらを提案するかに影響します）
   • 再レンダリングの場合：このコンポーネントはどのくらいの頻度で再レンダリングされますか？

使い方

このスキルは、コンテキストの使用量を最小限に抑えるため、段階的開示の構成になっています。

1. 概要（AGENTS.md）から始める

各ルールの簡潔な概要を確認するには、AGENTS.md を読んでください。

2. 必要に応じて特定のルールを読み込む

関連する最適化を特定したら、詳しい実装ガイダンスを確認するため、対応するリファレンスファイルを読み込みます。

再レンダリングの最適化：

• defer-state-reads.md
• extract-memoized-components.md
• narrow-effect-dependencies.md
• subscribe-derived-state.md
• functional-setstate-updates.md
• lazy-state-initialization.md
• transitions-non-urgent-updates.md
• calculate-derived-state.md
• avoid-usememo-simple-expressions.md
• extract-default-parameter-value.md
• interaction-logic-in-event-handlers.md
• no-inline-components.md
• useref-for-transient-values.md
• split-combined-hooks.md
• use-deferred-value.md

レンダリングのパフォーマンス：

• animate-svg-wrapper.md
• css-content-visibility.md
• hoist-static-jsx.md
• optimize-svg-precision.md
• prevent-hydration-mismatch.md
• activity-component-show-hide.md
• hoist-regexp-creation.md
• use-usetransition-over-manual-loading.md

高度なパターン：

• store-event-handlers-refs.md
• uselatest-stable-callbacks.md
• cache-repeated-function-calls.md
• initialize-app-once.md
• effect-event-deps.md

その他：

• named-imports.md
• no-forwardref.md

クイックリファレンス：

• quick-checklists.md
• compound-patterns.md
• react-compiler-guide.md

自動化スクリプト：

• scripts/ - アンチパターンを検出するためのヘルパースクリプト

3. パターンを適用する

各リファレンスファイルには、次の内容が含まれています。

• ❌ アンチパターンを示す誤った例
• ✅ 最適な実装を示す正しい例
• そのパターンが重要な理由の説明

4. レポートテンプレートを使用する

このスキルが呼び出されたときは、標準化されたレポート形式を使用します。

テンプレート： assets/output-report-template.md

レポート形式には、次の内容が含まれています。

• 影響評価を含むエグゼクティブサマリー
• 優先順位付けのための重大度レベル（Critical、High、Medium、Low）
• 影響分析（潜在的なバグ、型安全性、保守性、ランタイムエラー）
• 分類（型安全性、安全性、状態管理、戻り値、コード品質）
• 詳細なガイダンスを記載したreferences/内の資料へのリンク
• すべての問題を追跡するためのフェーズ2サマリーテーブル

監査テンプレートを使用する場合：

• スキルが /accelint-react-best-practices <path> から直接呼び出された場合
• ユーザーが「コード品質をレビュー」またはファイル全体の「コードを監査」するよう依頼し、スキルが暗黙的に呼び出された場合

レポートテンプレートを使用しない場合：

• ユーザーが「この型エラーを修正して」と依頼した場合（直接実装）
• ユーザーが「このコードの問題点は？」と尋ねた場合（質問に回答）
• ユーザーが具体的な修正を依頼した場合（正式なレポートを作成せず、直接修正を適用）

例

例1：再レンダリングの最適化

タスク：「ユーザーがスクロールすると、このコンポーネントが頻繁に再レンダリングされます」

アプローチ：

1. AGENTS.md の概要を読みます
2. 原因として考えられる点を特定します：スクロール位置など、連続的に変化する値を購読しています
3. subscribe-derived-state.md または transitions-non-urgent-updates.md を読み込みます
4. 参照ファイルのパターンを適用します

例2：古いクロージャーの修正

タスク：「このコールバックは常に古い state の値を使います」

アプローチ：

1. AGENTS.md の概要を読みます
2. 問題を特定します：useCallback 内の古いクロージャーです
3. functional-setstate-updates.md を読み込みます
4. state への直接参照を関数型の更新に置き換えます

例3：SSR のハイドレーション不一致

タスク：「localStorage のテーマでハイドレーションエラーが発生します」

アプローチ：

1. AGENTS.md の概要を読みます
2. 問題を特定します：クライアント専用の state が不一致を引き起こしています
3. prevent-hydration-mismatch.md を読み込みます
4. 同期スクリプトのパターンを実装します

スキルパターンを適切に使用する

各参照ファイルでは、実証済みのパターンを1つ紹介していますが、React の問題には複数の有効な解決策があることがよくあります。

パターンを適用する際は：

1. ✅ 参照ファイルのパターンを提示します
2. ✅ 他のアプローチがある場合は、それらにも言及します
3. ✅ ユーザーの React のバージョン、プロジェクトの複雑さ、チームの好みを考慮します
4. ✅ 単純なケースでは、参照ファイルにない場合でも、より単純な解決策を提案します

例： SSR のハイドレーション問題について、prevent-hydration-mismatch.md では同期スクリプトのアプローチを紹介していますが、基本的なユースケースでは単純な「マウント済みフラグ」パターンの方が適切な場合があります。

重要な注意事項

React Compiler について

手動で行う多くの最適化パターン（memo、useMemo、useCallback、静的 JSX の巻き上げ）は、React Compiler によって自動的に処理されます。

最適化の前に、プロジェクトで React Compiler が使用されているか確認してください：

• 有効な場合：手動のメモ化は省略しますが、state／effect／CSS の最適化は引き続き適用します
• 有効でない場合：このガイドの関連する最適化をすべて適用します

コンパイラーが処理する内容と、引き続き手動で最適化する必要がある内容の詳細については、react-compiler-guide.md を参照してください。

React 19 以降の機能

このスキルでは、次の React 19 の機能を扱います：

• 安定したイベントハンドラーを実現する useEffectEvent（19.2+）
• 非表示のコンポーネントの state を保持する <Activity> コンポーネント
• prop としての ref（非推奨の forwardRef を置き換えます）
• 名前付きインポートのみ（React のデフォルトインポートは不可）

パフォーマンスの考え方

• まず正しいコードを書き、その後に最適化します
• 最適化の前に計測します
• 最も遅い処理から最適化します（ネットワーク > レンダリング > 計算）
• 単純な処理を時期尚早に最適化するのは避けます

コード品質の原則

• 気の利いた最適化よりも、シンプルで読みやすいコードを優先します
• 計測結果に根拠がある場合にのみ、複雑さを加えます
• 一見して分かりにくいパフォーマンス最適化には説明を記述します

追加リソース

React 19 の機能について確認しましょう：

• React 19
• React 19.2
• React 19 Upgrade Guide