# バッチ設計書 7-build

## 概要

本ドキュメントは、Decap CMSプロジェクトにおけるbuildバッチのバッチ設計書である。package.jsonのscripts.buildで定義された、全パッケージのESMビルドおよびUMDビルドを実行するバッチ処理について記述する。

### 本バッチの処理概要

本バッチは、Decap CMSモノレポ内の全パッケージに対して、ESM（ES Modules）形式とUMD（Universal Module Definition）形式のビルドを順次実行するバッチである。まずbuild:esmで全パッケージのESMビルドを実行し、その後nx run-many -t buildで各パッケージのWebpackベースのUMDビルドを実行する。

**業務上の目的・背景**：Decap CMSは複数のnpmパッケージで構成されるモノレポプロジェクトであり、配布用のバンドルを生成するために2種類のビルドが必要である。ESM形式はモダンなバンドラー（webpack/rollup等）での利用向け、UMD形式はCDN経由でのscriptタグ読み込みやレガシー環境向けに提供される。本バッチはリリース前のパッケージビルドやCI/CDパイプラインの一部として使用される。

**バッチの実行タイミング**：手動実行（npm run build）、またはCI/CDワークフロー内でのステップとして実行される。No.3（Publish Packages）やNo.9（build:demo）の前段処理として呼び出される。

**主要な処理内容**：
1. npm run build:esm（全パッケージのESMビルド: nx run-many -t build:esm）
2. nx run-many -t build（各パッケージのWebpack UMDビルド）

**前後の処理との関連**：No.8（build:esm）を内部で呼び出す。No.9（build:demo）の前段として使用される。No.3（Publish Packages）のワークフロー内でも呼び出される。Nxのキャッシュ機能により、変更のないパッケージのビルドはスキップされる。

**影響範囲**：packages/配下の全パッケージのdistディレクトリにビルド成果物が生成される。各パッケージのdist/にUMDバンドル（{パッケージ名}.js）とsource mapが出力される。

## バッチ種別

ビルド（パッケージビルド - ESM/UMD出力）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動またはCI/CDから呼び出し） |
| 実行時刻 | 該当なし |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | npm run build（手動）/ CI/CDワークフロー内ステップ |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js実行環境 | Node.js（22.x以上推奨）がインストールされていること |
| npm依存関係 | npm ciまたはnpm installが完了していること |
| Nxの利用可能性 | nxコマンドが利用可能であること（devDependenciesにnx含む） |
| ソースコードの存在 | packages/配下の各パッケージにsrcディレクトリが存在すること |

### 実行可否判定

特別な実行可否判定ロジックは存在しない。npm run buildコマンドの実行により即座にビルドが開始される。Nxのキャッシュが有効な場合、変更のないパッケージはキャッシュからの復元によりスキップされる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| NODE_ENV | 環境変数 | No | development | productionの場合、本番用の最適化されたビルドが生成される |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| packages/*/src/ | TypeScript/JavaScript | 各パッケージのソースコード |
| packages/*/package.json | JSON | 各パッケージのメタ情報・依存関係 |
| packages/*/webpack.config.js | JavaScript | 各パッケージのWebpack設定（存在する場合） |
| scripts/webpack.js | JavaScript | 共通のWebpackビルド設定 |
| scripts/externals.js | JavaScript | 外部依存関係のマッピング定義 |
| nx.json | JSON | Nxの設定（キャッシュ、依存関係グラフ） |
| babel.config.js | JavaScript | Babel変換設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| packages/*/dist/ | JavaScript（UMD） | UMD形式のバンドルファイル |
| packages/*/dist/esm/ | JavaScript（ESM） | ESM形式のモジュールファイル |
| packages/*/dist/*.map | Source Map | デバッグ用のソースマップ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | UMD: {パッケージ名}.js / ESM: 各モジュールファイル |
| 出力先 | packages/*/dist/ |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし（JavaScriptファイル） |

## 処理フロー

### 処理シーケンス

```
1. npm run build:esm
   └─ nx run-many -t build:esm
       ├─ Nxが全パッケージを依存関係順に解決
       ├─ 各パッケージのbuild:esmタスクを実行
       ├─ dependsOn: ["^build:esm"] により依存パッケージを先にビルド
       └─ cache: trueによりキャッシュ活用
2. nx run-many -t build
   └─ 各パッケージのbuildタスクを実行
       ├─ Nxが全パッケージを依存関係順に解決
       ├─ scripts/webpack.jsの共通設定を使用
       ├─ scripts/externals.jsの外部依存関係マッピングを使用
       ├─ UMD形式のバンドルを生成（dist/{パッケージ名}.js）
       ├─ peerDependenciesをexternalsとして除外
       ├─ dependsOn: ["^build"] により依存パッケージを先にビルド
       └─ cache: trueによりキャッシュ活用
```

### フローチャート

```mermaid
flowchart TD
    A[npm run build] --> B[npm run build:esm]
    B --> C[nx run-many -t build:esm]
    C --> D[各パッケージのESMビルド: 依存順]
    D --> E{ESMビルド成功?}
    E -->|失敗| F[ビルドエラー]
    E -->|成功| G[nx run-many -t build]
    G --> H[各パッケージのWebpack UMDビルド: 依存順]
    H --> I{UMDビルド成功?}
    I -->|成功| J[ビルド完了]
    I -->|失敗| F
```

## データベース操作仕様

### 操作別データベース影響一覧

本バッチではデータベース操作は行わない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | 該当なし | 該当なし | 該当なし |

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ESMビルドエラー | TypeScript/Babelのコンパイルエラー | ソースコードの型エラーや構文エラーを修正する |
| - | Webpackビルドエラー | Webpack設定エラーまたはモジュール解決失敗 | webpack.config.jsの設定やインポートパスを確認する |
| - | 外部依存関係エラー | peerDependenciesのexternalsマッピングが未定義 | scripts/externals.jsに該当パッケージのマッピングを追加する |
| - | メモリ不足 | 大量パッケージの同時ビルドによるメモリ超過 | NODE_OPTIONSで--max-old-space-sizeを増加させる |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 自動リトライなし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

ビルド失敗時は以下の手順で対応する：
1. Nxのビルドログでどのパッケージ・どのファイルでエラーが発生したかを確認する
2. ESMビルドの場合はBabelの変換エラーを修正する
3. UMDビルドの場合はWebpackのビルドエラーを修正する
4. npm run clean でビルドキャッシュをクリアしてから再実行する

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（ファイルシステム操作のみ） |
| コミットタイミング | 該当なし |
| ロールバック条件 | npm run cleanで全ビルド成果物を削除可能 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 全パッケージ（約30パッケージ）のESM+UMDビルド |
| 目標処理時間 | 明示的な上限なし（通常5-15分程度、キャッシュ利用時は短縮） |
| メモリ使用量上限 | 明示的な上限なし（デフォルトのNode.jsヒープサイズ） |

## 排他制御

明示的な排他制御は設定されていない。Nxのビルドキャッシュにより、同時に同じパッケージのビルドが実行されることはない。distディレクトリへの書き込みは各パッケージで独立しているため、競合は発生しない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ビルド開始ログ | 各パッケージビルド開始時 | `Building [{パッケージ名}, library: {UMDグローバル名}]` |
| Nxタスクログ | タスク実行中 | Nxのタスク実行状況（キャッシュヒット含む） |
| Webpackログ | UMDビルド時 | Webpack統計情報（productionモード時は簡略表示） |
| エラーログ | ビルドエラー時 | FriendlyErrorsWebpackPluginによるフレンドリーなエラーメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ビルド成功/失敗 | 失敗時 | コンソール出力 / CI/CDログ |

## 備考

- scripts/webpack.jsが全パッケージ共通のWebpack設定を提供する
- scripts/externals.jsがパッケージ名をUMDグローバル名に変換するマッピングを提供する（例：decap-cms-app -> DecapCmsApp）
- UMDビルドではpeerDependenciesがexternalsとして除外される
- NODE_ENV=productionの場合、Webpackはproductionモードで最適化（minification等）を行う
- NODE_ENV=developmentの場合、umddir出力（dist/umd/index.js）が使用される
- Nxのキャッシュ設定（nx.json）により、build:esmとbuildの両方にキャッシュが有効化されている
- dependsOnによる依存関係解決で、パッケージのビルド順序が自動的に決定される
- Webpackの主要プラグイン：IgnorePlugin（esprima除外）、FriendlyErrorsWebpackPlugin、ProvidePlugin（Buffer）
- resolve.extensionsとして.ts, .tsx, .js, .jsonが設定されている
- resolve.fallbackでstreamモジュールがstream-browserifyにフォールバックされる
