react-ban-use-effect

React Ban useEffect

useEffectを直接使うのは、外部システムとの同期のための最終手段です。コンポーネントからは呼び出さず、実際の外部システムを扱う、レビュー済みのドメイン固有フックでのみ使用できます。

Scope

エフェクトの置き換えは、対象箇所の動作を変更します。リポジトリ全体への lint 適用は別のタスクです。依頼された場合、または既存のリポジトリポリシーで必須の場合に適用してください。レビュー依頼では指摘事項を提示し、実装依頼では、追加の承認を求めることなく、スコープ内の置き換えと検証が許可されます。

Workflow

1. 対象範囲内で、直接インポート、React.useEffect(...)による名前空間呼び出し、useEffectをラップする処理を見つけます。

2. 各エフェクトを分類し、次の優先順で置き換えます。

   1. レンダー時の計算
   2. サーバー、ローダー、またはフレームワークのデータ API
   3. リポジトリのサーバー状態レイヤー（たとえば、変数をキーに含め、signalを渡す TanStack Query のqueryOptionsファクトリー）
   4. イベントハンドラー、アクション、またはミューテーション
   5. キー付きコンポーネント境界
   6. useSyncExternalStore
   7. 実際の外部システムを扱う、レビュー済みのドメイン固有フック

   いずれも適合しない場合は、エフェクトを残す前に外部との同期契約を明記してください。わかりにくいケースについては置き換えを参照してください。

3. リポジトリのフレームワーク、データレイヤー、lint の形式、依存関係のポリシーを維持します。依頼またはリポジトリポリシーで許可されている場合に限り、ライブラリを追加してください。サーバー状態レイヤーがない場合は、残るエフェクトを設計上のギャップとして扱ってください。

4. lint、型、テストの各ゲートを実行し、変更した動作について、実際の UI またはフックを使った最小限のチェックを行います。

Legitimate Effects

正当なエフェクトはすべて、外部システムにちなんだ名前のフック（チャット接続、マップ SDK、ウィジェットなど）にまとめ、それぞれ別のファイルに配置します。フックがセットアップとクリーンアップを所有し、リアクティブな入力をパラメーターとして受け取り、セットアップまたはクリーンアップで読み取るすべての値を列挙します。フックを呼び出すコンポーネントにはエフェクトを置きません。既存のリポジトリフックがあれば、そちらを優先してください。

禁止事項：

• コールバックと呼び出し元が指定する依存配列を受け取る汎用ラッパーを作成すること（useUpdateEffect(fn, deps)、useAsyncEffect(fn, deps)、useMountEffect(fn)など）。
• react-hooks/exhaustive-depsを抑制すること。
• 例外的なフックを使ってサーバー状態を取得したり、propsをstateにコピーしたり、ユーザーアクションを中継したり、キー付き境界で行うべきリセットを隠したりすること。

Enforcement

適用が対象範囲に含まれる場合は、リポジトリ既存の linter を拡張し、名前付きのuseEffectインポートとReact.useEffect(...)呼び出しの両方を拒否します。許可するのは、名前が指定されレビュー済みのインテグレーションフックのファイルだけです。src/hooks/**のようなディレクトリを許可してはいけません。また、汎用ラッパーも許可してはいけません。ラッパーとその呼び出し元を、移行すべき違反として報告してください。標準のローカルゲートと CI では、同じ lint 対象範囲を維持してください。エージェント向けのガイダンスや任意のスキャナーで代用することはできません。恒久的な適用手段として、診断ツールの@latestを使わないでください。

レビューでは、新たに追加された直接的なエフェクトはすべて指摘事項として扱います。ただし、その変更で正当な外部システムとの境界が文書化され、立証されている場合を除きます。依存配列の調整ではなく、置き換えを求めてください。

Boundaries

• 移行の対象は、変更箇所または依頼された範囲に限定します。
• 依頼がない限り、lint ルールを含め、useLayoutEffect、useInsertionEffect、フレームワークのライフサイクル API、React 以外のエフェクトシステムには手を加えないでください。
• パフォーマンス関連のプリミティブを適用するのは、測定された動作またはリポジトリで確立されたパターンがある場合に限ります。
• 上流の出典：上流。