Skip to content
Architecture Decision Records

Adopt Three-Layer Component Architecture

コンテキスト

Section titled “コンテキスト”

フロントエンド開発において、コンポーネントの役割と管理方法を明確に分離する必要がある。現在、多くのプロジェクトで以下の課題が存在する。

  • 汎用的なUIコンポーネントとアプリケーション固有のコンポーネントが混在し、再利用性が低下している
  • コンポーネントライブラリとして管理すべきものとアプリケーション側で管理すべきものの境界が曖昧である
  • 画面コンポーネントとビジネスロジックを含むコンポーネントの責務が不明確である
  • WebアプリケーションとNativeアプリケーションで用語が統一されていない

複数のプロダクト間でコンポーネントを共有する場合、明確な階層分けがないと重複実装や保守性の低下につながる。

決定事項

Section titled “決定事項”

コンポーネントを以下の3層に明確に分離する。

  1. UIコンポーネント層: アプリケーション固有の機能を持たない汎用的なコンポーネント群

    • npm packageとして独立管理
    • 複数プロダクトで共通利用

  2. Componentコンポーネント層: アプリケーション固有の機能を持つコンポーネント群

  3. Page/Screenコンポーネント層: 各画面を構成するコンポーネント群

    • ルーティングとデータ取得パラメータの組み立てを責務とする
    • WebアプリケーションはPage、NativeアプリケーションはScreenという命名規則

選択肢

Section titled “選択肢”

選択肢1: 3層アーキテクチャ（採用案）

Section titled “選択肢1: 3層アーキテクチャ（採用案）”

  • 利点:

    • 各層の責務が明確で、開発者が迷わない
    • 再利用可能なコンポーネントの管理が容易
    • プロダクト間でのコンポーネント共有が促進される
    • パッケージ化により依存関係が明確になる
    • Web/Native間での概念の統一が図れる

  • 欠点:

    • 初期設計時に層の分類を慎重に検討する必要がある
    • npm package管理のオーバーヘッドが発生する
    • 層間の依存関係管理が複雑になる可能性がある

選択肢2: 2層アーキテクチャ（共通/アプリケーション固有）

Section titled “選択肢2: 2層アーキテクチャ（共通/アプリケーション固有）”

  • 利点:

    • シンプルな構造で理解しやすい
    • 管理コストが比較的低い
    • 既存プロジェクトからの移行が容易

  • 欠点:

    • Page/Screenレベルのコンポーネントの扱いが曖昧になる
    • ビジネスロジックとプレゼンテーション層の混在が起こりやすい
    • 責務の境界が不明確になりやすい

選択肢3: 単一層（フラット構造）

Section titled “選択肢3: 単一層（フラット構造）”

  • 利点:

    • 最もシンプルな構造
    • 学習コストが低い
    • 小規模プロジェクトでは十分な場合がある

  • 欠点:

    • プロジェクト規模拡大時に管理が困難
    • 再利用性が低下する
    • コンポーネント間の依存関係が複雑になる
    • 複数プロダクト間での共有が困難

結果

Section titled “結果”

この決定による影響を記述する。

  • ポジティブな影響:

    • コンポーネントの責務が明確になり、開発効率が向上する
    • デザインシステムの一貫性が保たれる
    • 複数プロダクト間でのコード共有が促進される
    • テストの粒度と範囲が明確になる
    • 新規開発者のオンボーディングが容易になる

  • ネガティブな影響:

    • 初期設定とパッケージ管理のコストが増加する
    • 層間の依存関係管理に注意が必要となる
    • リリースサイクルの調整が必要になる可能性がある

  • リスク:

    • 層の分類を誤ると、後からの変更コストが高くなる
    • npm packageのバージョン管理が複雑になる可能性がある
    • 過度な抽象化により、シンプルな実装が複雑になるリスクがある

実装ガイドライン

Section titled “実装ガイドライン”

UIコンポーネント層

Section titled “UIコンポーネント層”
@company/ui-components/
  Button/
  Input/
  Modal/
  Table/
  DatePicker/
  etc...
  • ビジネスロジックを含まない
  • プロップスは汎用的なインターフェース
  • Storybookでのドキュメント化必須

Componentコンポーネント層

Section titled “Componentコンポーネント層”
src/components/
  UserProfile/
  UserSettings/
  ProductCard/
  ProductList/
  OrderSummary/
  etc...
  • OOUIの命名規則に従う（モデル名 + UI種別）
  • アプリケーション固有のビジネスロジックを含む
  • UIコンポーネント層を組み合わせて構築

Page/Screen層

Section titled “Page/Screen層”
src/pages/         # Web
  UserDetailPage/
  ProductListPage/
  CheckoutPage/


src/screens/       # Native
  UserDetailScreen/
  ProductListScreen/
  CheckoutScreen/
  • ルーティングパラメータの処理
  • データ取得の調整
  • Componentコンポーネントの組み合わせ

参考資料

Section titled “参考資料”