modern-web-app-architecture

モダンな Web アプリケーションアーキテクチャ（SPA／SSR／SSG／RSC）

概要

モダンな Web アプリケーション（SPA やハイブリッドレンダリングアプリを含む）の設計と構築に関する包括的なガイダンスです。このスキルでは、トレードオフ、明確な境界、本番環境で利用できる実践方法（パフォーマンス、アクセシビリティ、セキュリティ、テスト、デリバリー）を重視します。

基本原則： アーキテクチャにおけるあらゆる要素はトレードオフです。「正解」はなく、特定のコンテキストにおいて最も問題の少ない組み合わせがあるだけです。

動作モード（このスキルの使い方）

有効化されたら、次の順に進めます。

1. コンテキストを明確にする（質問は最大5～10個） → ユーザー、ルート、SEO、インタラクティブ性、データ、認証、チーム、制約。
2. ルートごとにレンダリング戦略を選択する（「アプリ全体で1つの戦略」にはしない）。
3. 境界を定義する → 機能／ドメインモジュール、共有ライブラリ、所有権、安定したインターフェース。
4. 状態とデータを計画する → ローカル／共有／グローバル／サーバー／URL の状態、キャッシュ戦略、無効化、楽観的更新。
5. 非機能要件を計画する → パフォーマンス予算と測定、アクセシビリティ計画、セキュリティ態勢、可観測性。
6. 成果物を作成する → トレードオフを明示した簡潔な推奨事項と、具体的な次のステップ（フォルダー構成、ADR、チェックリスト）。

ユーザーが質問に答えられない場合は、妥当な前提を明示して続行します（作業を止めないでください）。

使用する場面

• 新しい SPA または Web アプリケーションを始めるとき
• レンダリング戦略（CSR、SSR、SSG、ISR、RSC）を選ぶとき
• 状態管理を実装するとき
• Core Web Vitals（LCP／INP／CLS）を最適化するとき
• 複数のフロントエンドチームに対応できるよう拡張するとき
• アーキテクチャのトレードオフを判断するとき
• レガシーなフロントエンドからモダンなフロントエンドへ移行するとき

初期確認の質問（最初に尋ねる）

• 主なユーザージャーニーを3つ挙げ、それぞれの目標レイテンシを教えてください（例：「検索 → 商品 → 決済」）。
• SEO が必要なルートはありますか？公開されているルートと認証が必要なルートはどれですか？
• データの形態はどのようなものですか？主に CRUD、リアルタイム、オフライン優先、複雑なフォーム、大規模なテーブル／チャートのどれに当たりますか？
• 制約は何ですか？ ブラウザーのサポート範囲、バンドルサイズの上限、市場投入までの期間、コンプライアンス（SOC2／HIPAA／PCI）などです。
• チーム構成はどうなっていますか？開発者やチームの数、リリース頻度、所有権の境界を教えてください。
• 希望するスタック（React／Vue／Angular／vanilla）は何ですか？TypeScript の使用は可能ですか？

参考ファイル

トピック	読み込むタイミング
@references/design-patterns.md	JavaScript のパターン（Module、Observer、Factory など）を実装するとき
@references/react-patterns.md	React のコンポーネント、フック、状態、コンポジションを扱うとき
@references/spa-fundamentals.md	SPA のアーキテクチャ、ルーティング、モジュール構成を扱うとき
@references/micro-frontends.md	チームを拡大し、独立したデプロイを行うとき
@references/performance.md	バンドルサイズ、読み込み、Core Web Vitals を扱うとき
@references/architecture-decisions.md	トレードオフ、結合、適合性関数を扱うとき
@references/rendering-strategies.md	CSR と SSR、SSG、ISR、RSC を比較するとき
@references/state-management.md	ローカル、グローバル、サーバー状態のパターンを扱うとき
@references/security-and-auth.md	認証の選択肢、トークンの保存、XSS／CSRF、CSP、API の境界を扱うとき
@references/accessibility-and-i18n.md	WCAG の基本、SPA のフォーカス管理、インクルーシブなコンポーネント、i18n の落とし穴を扱うとき
@references/testing-and-quality.md	テスト戦略、CI の品質ゲート、アクセシビリティチェック、コントラクトテストを扱うとき
@references/tooling-and-delivery.md	バンドル、環境、デプロイ、可観測性、機能フラグを扱うとき

アーキテクチャの簡易判断ツリー

Project Requirements?
├─ SEO critical + dynamic content → SSR (or SSR+streaming)
├─ SEO critical + mostly static → SSG/ISR (or hybrid)
├─ Mostly behind auth + app-like UX → CSR SPA (or hybrid with pre-rendered shell)
├─ Mixed (marketing + app) → Hybrid/Islands (route-level strategy)
│
Team Size?
├─ <5 developers → Modular monolith SPA
├─ 5-15 developers → Well-structured SPA or Service-based
├─ >15 developers, multiple teams → Consider micro-frontends
│
Domain Complexity?
├─ Simple CRUD → Layered architecture
├─ Complex workflows → Domain-partitioned (DDD)
├─ Multiple bounded contexts → Micro-frontends

デフォルトの出力（作成する内容）

ユーザーのリクエストに応じて、以下の出力を目指します：

• ルート戦略マップ：ルート → CSR／SSR／SSG／ISR／RSC とその理由をまとめた小さな表
• モジュール境界の概要：機能フォルダー、共有ライブラリ、インターフェースの契約
• 状態マップ：ローカル／共有／グローバル／サーバー／URL と、選択したツールのパターン
• データ計画：キャッシュ／無効化、エラー状態、楽観的更新、ページネーション
• 品質計画：テストレイヤー + CI ゲート + アクセシビリティチェック
• パフォーマンス計画：予算 + 計測 + 具体的な読み込み戦略（分割ポイント）
• リスク一覧：上位 5 件のリスク + 軽減策（例：ハイドレーションのコスト、認証の態勢、チーム間の結合）

重要なパターンのクイックリファレンス

コンポーネントパターン

パターン	使用する場面
コンテナー／プレゼンテーション	データと UI を分離する
複合コンポーネント	組み合わせ可能な API（Select、Menu）を構築する
フック	HOC を使わずに状態を持つロジックを共有する
プロバイダー	グローバルデータのプロップドリリングを避ける

状態管理

アプローチ	使用する場面
useState/useReducer	コンポーネントのローカル状態
Context	テーマ、認証、更新頻度の低いグローバル状態
Zustand/Jotai	シンプルなグローバル状態、最小限の定型コード
Redux Toolkit	複雑な状態、タイムトラベルデバッグ
React Query/SWR	サーバー状態、キャッシュ、バックグラウンド更新
XState	明示的な状態機械を使う複雑なフロー

パフォーマンスの要点

手法	効果
コード分割	初期バンドルを小さくする
遅延読み込み	重要でない処理の読み込みを遅らせる
React.memo	不要な再レンダリングを防ぐ
useMemo/useCallback	参照を安定させる
仮想リスト	大規模なデータセットに対応する

アーキテクチャ特性（3～7 個を選択）

特性	確認する質問
スケーラビリティ	同時ユーザー数はどれくらいですか？成長率はどれくらいですか？
パフォーマンス	許容できる TTI はどれくらいですか？LCP の目標値は？
デプロイ可能性	どのくらいの頻度でリリースしますか？独立してデプロイしますか？
テスト容易性	変更の検証はどのくらい簡単ですか？
保守性	想定される寿命はどれくらいですか？
モジュール性	要件はどのくらいの頻度で変わりますか？

避けるべきアンチパターン

アンチパターン	問題	解決策
プロップドリリング	密結合	Context または状態管理
巨大なコンポーネント	責務が多すぎる	関心ごとごとに分割する
早すぎる最適化	根拠のない複雑さ	まずプロファイルする
共有された可変状態	競合状態、バグ	不変パターン
モノリシックなバンドル	初期読み込みが遅い	コード分割
過剰なデータ取得	帯域幅の浪費	GraphQL または BFF
デフォルトで LocalStorage にトークンを保存	XSS によってアカウントが乗っ取られる	httpOnly Cookie + CSP を優先する（セキュリティの参考資料を参照）
サーバーデータにグローバルストアを使用	キャッシュ無効化が困難	サーバー状態には React Query/SWR を使用する

パフォーマンス予算

予算はユーザーやデバイスに合わせて調整する必要がありますが、これらは「デフォルトで高速」なアプリを作るための良い出発点です：

指標	目標	要改善
LCP	<2.5s	2.5–4s
INP	<200ms	200–500ms
CLS	<0.1	0.1–0.25
TTFB	<800ms	800ms–1.8s
ルートの JS（初期）	<170KB gzip	<300KB gzip

出典

以下の資料を統合：

• Learning JavaScript Design Patterns（Osmani、2023）
• React in Depth（Barklund、2024）
• SPA Design and Architecture（Scott）
• Single Page Web Applications（Mikowski & Powell）
• Building Micro-Frontends（Mezzalira）
• Micro Frontends in Action（Geers）
• Responsible JavaScript（Wagner）
• High Performance Browser Networking（Grigorik）
• Web Performance in Action（Wagner）
• Frontend Architecture for Design Systems（Godbolt）
• Fundamentals of Software Architecture（Richards & Ford）
• Software Architecture: The Hard Parts（Ford ほか）
• Patterns.dev