react-frontend

React フロントエンド

実装前に確認してください：App Router のパターン、React 19 の API、またはバージョン固有の動作については、コードを書く前に最新のドキュメントを調べてください（利用可能であれば Context7 の query-docs、それ以外の場合はウェブ検索でフレームワークの公式ドキュメントを確認します）。学習データは最新リリースに追いついていない可能性があります。

作業ルール

• 派生状態はレンダー中に計算し、ユーザー操作はイベントハンドラーで処理します。エフェクトは外部との同期に使用します。
• 非同期処理にはライフサイクルとキャンセル方針を設けます。失敗は処理中やデータなしの状態とは分けて表現します。
• キャッシュキーをリクエストの識別情報に結び付けてください。 サーバーのセッション状態が先に変わると、テナント単位のキーに別のテナントのレスポンスが入る可能性があります。コンテキストの切り替え中は、リクエストのスコープとキャッシュの識別情報を一貫させてください。マウント済みのコンシューマー、進行中のリクエスト、失敗した再取得を使って分離を検証してください。
• インタラクティブな領域を非表示にするときはフォーカスを維持し、実際のブラウザーでキーボード操作を確認してください。
• すべての公開サーバーアクションを検証・認可し、サーバーとクライアントの境界を越えて送信するフィールドは必要なものだけにしてください。
• パフォーマンスの変更は測定し、型チェックだけでなく、ユーザーから見える動作もテストしてください。

エフェクトの判断フロー

エフェクトは回避策です。ほとんどのロジックでエフェクトを使うべきではありません。

必要な処理	解決策
props/state からの派生値	レンダー中に計算する（高コストの場合は useMemo を使用）
prop の変更時に状態をリセットする	コンポーネントに key prop を設定する
ユーザーイベントに応答する	イベントハンドラー
親に状態変更を通知する	イベントハンドラーで onChange を呼び出すか、完全に制御されたコンポーネントを使用する
状態更新を連鎖させる	1 つのイベントハンドラー内ですべての次の状態を計算する
外部システムと同期する	クリーンアップ付きのエフェクト

エフェクトのルール：

• リンターを決して抑制せず、代わりにコードを修正してください
• アップデーター関数（setItems(prev => [...prev, item])）を使用して、状態への依存をなくしてください
• オブジェクトや関数はエフェクト内に移動して、依存関係を安定させてください
• リアクティブでない値（例：接続エフェクト内のテーマ）には useEffectEvent を使用してください
• サブスクリプション、接続、リスナーには必ずクリーンアップを返してください
• データ取得のキャンセル方法（状況に応じて選択）：fetch には AbortController、キャンセルできないプロミスには ignore フラグを使用します。React Query では、queryFn: ({ signal }) => fetch(url, { signal }) のように、クエリ関数のシグナルをトランスポートに渡してください。そのシグナルを消費しない場合、未使用のクエリが完了してキャッシュにデータを登録することがあります。この動作をトランスポートのキャンセルとして説明しないでください。
• リクエストの完了は初期化の完了を意味しません。 使用可能なデータを適用した後、またはデータがないことが正常に確定した後にのみ、一度限りの初期化ラッチを消費してください。同じマウント内で「データなし」の後にデータが取得されるケースをテストしてください。後続の再取得でユーザーの編集内容が維持されることを確認してください。

規律

• まずシンプルに：変更は可能な限りシンプルにし、影響するコードを最小限に抑えます
• 必要な箇所だけを変更し、無関係な変更は避けます
• その場しのぎの回避策は避けます。修正が適切でないと感じたら、立ち止まって適切な解決策を実装します
• 新しい抽象化を追加する前に、3 か所以上で使われることを確認します

参考資料

• testing.md：コンポーネント、フック、モックのテスト例
• e2e-testing.md：Playwright の E2E パターン

検証

• TypeScript がエラーなしでコンパイルされること
• 新しいコードにリンター規則の抑制（eslint-disable、@ts-ignore）がないこと
• useEffect の依存配列を手動で上書きしていないこと
• React 19 以降のプロジェクトでは forwardRef を使用せず、代わりに ref prop を直接使用すること

タスク固有のリファレンス

該当する動作を実装またはレビューする前に、関連するリファレンスをお読みください。

• コンポーネントの種類、状態の所有権、非同期処理の競合、フォーカス、またはキャッシュされたクエリの動作については、components-and-state.mdをご覧ください。
• パフォーマンス、React API、Next.js の境界、またはキャッシュについては、rendering-and-frameworks.mdをご覧ください。
• Tailwind CSS のユーティリティ、@theme トークン、CVA/tailwind-variants、ダークモード、v3 から v4 への移行、またはオーバーフローやhiddenに関する落とし穴については、tailwind.mdをご覧ください。
• コンポーネント、フック、ブラウザー、または統合テストの変更については、test-selection.mdをご覧ください。
• JSON ロケールファイルの同期や翻訳のレビューについては、locale-synchronization.mdをご覧ください。

該当するトピックに応じて参照する既存の専門リファレンス：

• tailwind.mdで扱うTailwindの詳細については、tailwind-configuration.md、tailwind-v3-to-v4.md、tailwind-class-composition.md、tailwind-component-patterns.md、tailwind-layout-patterns.mdをご覧ください。