bulletproof-react-architecture

Bulletproof React のアーキテクチャ

出典：bulletproof-react、Alan Alickovic 作、MIT ライセンス。上流リポジトリは現在、3 つのアプリバリアントを含むモノレポになっています：apps/react-vite/、apps/nextjs-app/、apps/nextjs-pages/。このスキルでは、react-vite 版を主に参照します。ライセンスと改変に関する注記は NOTICE.md をご覧ください。

用語

以下の用語をそのまま使用してください。このリポジトリで「feature」を指している場合に、「module」「service」「component」に置き換えないでください。

• Feature：src/features/ 配下にある自己完結型のフォルダーです。製品機能の一部分に固有のすべてを格納します。独自の api/、components/、hooks/、stores/、types/ を持ちます。
• Shared code：トップレベルの components/、hooks/、lib/、types/、utils/ にあるものすべてです。どの feature からでも、アプリレイヤーからでも使用できます。feature に依存することはありません。
• App layer：src/app/ を指し、ルート、ルートコンポーネント、プロバイダー、ルーター設定が含まれます。複数の feature を組み合わせられる唯一のレイヤーです。

目安となるルール

ざっと確認できる要約です。それぞれの詳細は、以下にリンクされているリファレンスファイルで説明しています。

ルール	意味
feature 間でインポートしない	features/comments から features/discussions をインポートするのは、常にバグです。共有コードに移してください。
コードは一方向に流れる	shared → features → app。逆方向は禁止です。shared から feature や app をインポートすることはできません。
まず状態のカテゴリーに合わせる	コンポーネント、アプリ、サーバーキャッシュ、フォーム、URL の状態は、それぞれ異なる問題であり、それぞれに異なるツールがあります。

適用する前に

この方法は、アプリに複数の feature がある場合、貢献者が複数いる場合、または開発期間が数か月を超える場合に効果を発揮します。5 ファイルのプロトタイプ、単発のスクリプト、使い捨てのコンポーネントには適していません。

構造を導入する前に、規模を確認してください。

• feature が 1 つで、ファイルが数個だけですか？ src/ をフラットなままにしてください。1 つのコンポーネントと 1 回のフェッチ呼び出しのために、feature フォルダーの構成一式を用意するのは、このスキルが防ごうとしている失敗パターンであり、目標ではありません。
• このコードベースですでに有効なパターンがありますか？ それに合わせてください。競合する 2 つの規約は、どちらか一方の不完全さよりもコストがかかります。
• ルールが当てはまるか判断できませんか？ そのルールがないと何が壊れるのかを考えてください。何も壊れないなら、適用しないでください。

以下のリファレンスファイルはチェックリストではありません。それぞれが 1 つの問題を解決します。目の前の問題に当てはまるものを読んでください。

このスキルが適用されない場合

バグ修正、単一関数の作成、コンポーネントのスタイリングなど、構造に関わらない作業では使用しないでください。「これはどこに置くべきか」または「どう整理すべきか」が問いではないなら、このスキルは必要ありません。

このスキルでは、規模に応じた判断を行うことを前提としています。プロジェクト構成ファイルに記載されているというだけで、すべてのサブフォルダーを作ろうとしていることに気づいたら、いったん手を止め、この feature に本当にすべて必要なのか考えてください。

注意点

エージェントが特によくする間違い：

1. react-router-domを使う。 上流のリポジトリはreact-router v7（ライブラリモード）に移行しました。react-router-domではなく、react-routerからインポートしてください。
2. 1つのコンポーネント内でしか使わない状態のストアを作る。 それはアプリケーションの状態ではなく、コンポーネントの状態です。まずはuseStateを使ってください。別のコンポーネントでも同じ値が必要になったときにだけ、ストアに移行します。
3. 小さな機能のために、機能全体の骨組みを作る。 コンポーネントが1つで、フェッチの呼び出しが1回だけの機能に、api/、components/、hooks/、stores/、types/は必要ありません。api/とcomponents/だけで十分です。必要になれば、後からフォルダーを追加できます。
4. サーバーキャッシュの状態をZustand、Redux、その他の汎用ストアに入れる。 サーバーデータは手作りのストアではなく、TanStack Queryのキャッシュに置きます。クエリクライアントが提供するキャッシュ、無効化、再フェッチのロジックをそのまま使えることこそ、TanStack Queryが存在する理由です。
5. バレルファイル（すべてを再エクスポートするindex.ts）。 Viteのツリーシェイキングを妨げます。必要なファイルから直接インポートしてください。
6. 機能をまたいだインポート。 繰り返しますが、features/commentsからfeatures/discussionsに手を伸ばすのは、決して適切な方法ではありません。2つの機能でロジックを共有する場合は、共有コードに移してください。
7. api/ファイルが1つだけであることを、過剰設計と指摘する。 features/x/api/にエンドポイントを1つ置くのは、APIレイヤーの始まりであり、ルール違反ではありません。過剰設計のチェック対象は、空のstores/、1か所でしか使わないhooks/、型が1つだけのtypes/フォルダー、または機能の外にある、本当に一度きりのインラインのフェッチです。実際の機能フォルダー内にすでに存在する、単独のapi/ファイルではありません。
8. データの変換やユーザーイベントの処理にuseEffectを使う。 既存のpropsや状態から計算できることは、レンダリング中に計算してください。ユーザーの操作をきっかけに実行するロジックは、イベントハンドラーに置いてください。エフェクトは外部システムとの同期にのみ使います。reference/effects.mdを参照してください。

参考になるリソース

各ファイルはすべて読み込んでも短い内容です。現在のタスクに関連するものをお読みください。

• reference/project-structure.md：アプリと機能のフォルダー構成、および前述のインポート方向を強制する ESLint ルールを説明します。新機能を追加するときや、「これはどこに置けばよいか」という疑問があるときは、まずこちらをお読みください。このスキルで最もよく読まれているファイルです。

• reference/api-layer.md：リクエストの宣言構造（型、フェッチャー、フック）を説明します。データ取得コードを作成またはレビューする際にお読みください。

• reference/state-management.md：5 つの状態カテゴリと、それぞれに推奨されるライブラリを説明します。useState、コンテキスト、ストアを追加する前にお読みください。通常、カテゴリを決める前にツールを選ぶと、誤った選択につながります。

• reference/testing.md：テストの種類、注力すべき箇所、ツール（Vitest、Testing Library、Playwright、MSW）について説明します。

• reference/error-handling.md：API エラーのインターセプト、エラーバウンダリーの配置、本番環境でのエラー追跡について説明します。短いので、すべてお読みください。

• reference/security.md：トークンの保存、認可モデル（RBAC、PBAC）について説明します。一部だけでなく、すべてお読みください。保存とサニタイズに関するガイダンスは互いに依存しています。ここでセクションを読み飛ばすと、時間を無駄にするだけではなく、実際の脆弱性につながるおそれがあります。

• reference/performance.md：コード分割、再レンダーの原因、children パターン、画像とプリフェッチの最適化について説明します。先回りして読むのではなく、計測可能な遅さがある場合にお読みください。

• reference/overengineering-check.md：このスキル独自の規約が、見合う効果のない箇所に適用されていないかを確認するための、範囲を絞ったレビュー手順です。不要な構造がないかコードベースをレビューするときや、機能のひな形を生成した後にセルフチェックするときにお読みください。

• reference/effects.md：Effects を避けるべき場合と、その代わりに何をすべきかを説明します。派生状態、useMemo、キーを使った状態のリセット、計算の連鎖、クリーンアップ付きのデータ取得などを取り上げています。useEffect を使う前にお読みください。

• reference/quality-check.md：これらの規約を適用または拡張する補助ツール（react-doctor、Vercel のパフォーマンスルール、コンポジションパターン）について説明します。