# webpack 業務運用マニュアル

## 目次

**【基本操作】**
1. [システム概要](#1-システム概要)
2. [インストール・初期設定](#2-インストール初期設定)
3. [CLIインターフェース（コマンド操作）](#3-cliインターフェースコマンド操作)

**【業務フローに沿った機能】**
4. [【STEP1】設定ファイルの作成（webpack.config.js）](#4-step1設定ファイルの作成webpackconfigjs)
5. [【STEP2-3】バンドル実行・コード分割（ビルドの実行・最適化）](#5-step2-3バンドル実行コード分割ビルドの実行最適化)
6. [【STEP3-4】開発モード・HMR（開発効率の向上）](#6-step3-4開発モードhmr開発効率の向上)
7. [【STEP4-5】ビルド結果の確認・本番デプロイ（成果物の検証と公開）](#7-step4-5ビルド結果の確認本番デプロイ成果物の検証と公開)

**【高度な機能】**
8. [Module Federation（マイクロフロントエンド）](#8-module-federationマイクロフロントエンド)
9. [アセット管理・CSS対応](#9-アセット管理css対応)
10. [プラグインシステム](#10-プラグインシステム)

**【運用ガイド】**
11. [日常業務の流れ](#11-日常業務の流れ)
12. [よくある質問と対処法](#12-よくある質問と対処法)
13. [トラブルシューティング](#13-トラブルシューティング)

---

## 1. システム概要

### 1.1 webpackとは

webpack（バージョン5.105.3）は、JavaScript アプリケーション向けの**モジュールバンドラー**です。ECMAScript / CommonJS / AMD 形式のモジュールをブラウザやNode.js環境で動作する形にバンドル（結合・変換）し、アプリケーションの配布に最適化された成果物を生成します。

主な特徴：
- 複数のモジュール形式（ES Modules、CommonJS、AMD）に対応
- コード分割（Code Splitting）による効率的なリソース読み込み
- Tree Shaking による未使用コードの自動除去
- Hot Module Replacement（HMR）による高速な開発体験
- 豊富なプラグインエコシステムによる拡張性
- Module Federation によるマイクロフロントエンドアーキテクチャの実現

### 1.2 本システムで行う主要業務

本システムは、主に以下の業務を支援します：

| 業務カテゴリ | 具体的な業務内容 |
|------------|----------------|
| **ビルド・バンドル** | ソースコードのバンドル、エントリポイント管理、出力ファイル生成 |
| **最適化** | コード分割、Tree Shaking、モジュール連結（Scope Hoisting）、チャンクマージ |
| **開発支援** | 開発サーバー起動、HMR（ホットリロード）、ソースマップ生成、遅延コンパイル |
| **アセット管理** | 画像・フォント等のアセットモジュール化、CSS処理、WebAssembly対応 |
| **マイクロフロントエンド** | Module Federation によるアプリケーション間モジュール共有 |
| **分析・レポート** | ビルド統計出力、パフォーマンス警告、プロファイリング |

### 1.3 業務フロー概要

本システムにおけるビルド業務は、以下の流れで進行します：

```
┌─────────────────────────────────────────────────────────────────┐
│                     webpack ビルド業務フロー                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  【STEP 1】設定ファイル（webpack.config.js）の作成・編集            │
│      ↓                                                          │
│  【STEP 2】webpack コマンドによるビルド実行                         │
│      ↓                                                          │
│  【STEP 3】コード分割・最適化の適用                                │
│      ↓                                                          │
│  【STEP 4】ビルド結果（Stats）の確認・パフォーマンス検証             │
│      ↓                                                          │
│  【STEP 5】本番向け成果物の確定・デプロイ                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

**役割別の業務概要：**

| 役割 | 主な業務 |
|------|---------|
| **アプリケーション開発者** | webpack設定の作成、ビルド実行、開発サーバー利用、エラー対応 |
| **ビルドエンジニア / CI管理者** | ビルドパイプラインの構築、最適化設定、パフォーマンス監視、本番ビルドの管理 |
| **ライブラリ開発者** | ライブラリ出力形式（UMD / CommonJS / ESM）の設定、DLL構成 |

### 1.4 主な機能

| 機能 | 説明 | 業務フローでの位置 |
|------|------|------------------|
| 設定管理 | webpack.config.js による設定定義、スキーマバリデーション、オプション正規化 | STEP 1 |
| バンドル実行 | エントリポイントからモジュール依存関係を解析しバンドルを生成 | STEP 2 |
| コード分割 | SplitChunksPlugin による共通モジュール分離、動的インポートによる遅延読み込み | STEP 2-3 |
| 最適化 | Tree Shaking、Scope Hoisting、チャンクマージ、エクスポート名マングリング | STEP 3 |
| HMR | Hot Module Replacement によるモジュール差分更新 | 開発時随時 |
| ビルド統計 | Stats JSON / テキストレポートによるビルド結果の分析 | STEP 4 |
| プラグイン | DefinePlugin / BannerPlugin / EnvironmentPlugin 等の組込みプラグイン | STEP 1（設定時） |
| Module Federation | マイクロフロントエンドアーキテクチャの実現 | STEP 1-2 |

### 1.5 ユーザー種別

システムには以下のユーザー種別があります：

| ユーザー種別 | 説明 |
|-------------|------|
| アプリケーション開発者 | Webアプリケーションの開発でwebpackをビルドツールとして利用するエンドユーザー |
| ビルドエンジニア | CI/CDパイプラインでのwebpack設定・最適化を担当するエンジニア |
| ライブラリ開発者 | npmパッケージやライブラリの配布用バンドルを作成する開発者 |
| プラグイン開発者 | webpackのプラグインやローダーを開発する拡張開発者 |

### 1.6 対応環境

推奨環境：
- Node.js 10.13.0 以上
- npm / yarn / pnpm（パッケージマネージャ）
- webpack-cli（CLIインターフェース用、別途インストール）

対応モジュール形式：
- ECMAScript Modules（import / export）
- CommonJS（require / module.exports）
- AMD（define / require）
- WebAssembly（.wasm）
- CSS（.css）

---

## 2. インストール・初期設定

### 2.1 インストール方法

1. プロジェクトディレクトリで以下のコマンドを実行し、webpackをインストールします

**入力コマンド：**

| パッケージマネージャ | コマンド |
|-------------------|---------|
| npm | `npm install --save-dev webpack webpack-cli` |
| yarn | `yarn add -D webpack webpack-cli` |
| pnpm | `pnpm add -D webpack webpack-cli` |

2. インストールが完了すると、`node_modules/.bin/webpack` コマンドが利用可能になります
3. `package.json` の `scripts` にビルドコマンドを追加します

```json
{
  "scripts": {
    "build": "webpack",
    "dev": "webpack serve",
    "watch": "webpack --watch"
  }
}
```

### 2.2 webpack-cli の自動インストール

webpackコマンドを初回実行した際に `webpack-cli` がインストールされていない場合、自動的にインストールを促すメッセージが表示されます（`bin/webpack.js`）。

```
CLI for webpack must be installed.
  webpack-cli (https://github.com/webpack/webpack-cli)

We will use "npm" to install the CLI via "npm install -D webpack-cli".
Do you want to install 'webpack-cli' (yes/no):
```

> **注意**: パッケージマネージャは、プロジェクト内の `yarn.lock`（yarn）、`pnpm-lock.yaml`（pnpm）の有無で自動判定されます。

### 2.3 初期設定ファイルの作成

webpack 5 では設定ファイルがなくてもデフォルト設定で動作しますが、プロジェクト要件に合わせた設定ファイルの作成を推奨します。

プロジェクトルートに `webpack.config.js` を作成します：

```javascript
const path = require('path');

module.exports = {
  mode: 'production',     // 'development' | 'production' | 'none'
  entry: './src/index.js', // エントリポイント
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js'
  }
};
```

---

## 3. CLIインターフェース（コマンド操作）

### 3.1 基本コマンド

webpackの操作はすべてコマンドラインから実行します。

| コマンド | 説明 |
|---------|------|
| `webpack` | デフォルト設定でビルドを実行 |
| `webpack --mode development` | 開発モードでビルド |
| `webpack --mode production` | 本番モードでビルド |
| `webpack --watch` | ファイル変更を監視し自動リビルド |
| `webpack --config webpack.config.js` | 指定した設定ファイルでビルド |
| `webpack --progress` | ビルド進捗をパーセンテージ付きで表示 |
| `webpack --json` | ビルド統計をJSON形式で出力 |

### 3.2 npm scripts からの実行

通常は `package.json` の `scripts` に登録して使用します。

```bash
# ビルド実行
npm run build

# 開発サーバー起動
npm run dev

# ファイル監視モード
npm run watch
```

### 3.3 プログラマティックAPI

Node.jsスクリプトからwebpackを直接呼び出すことも可能です（`lib/index.js`）。

```javascript
const webpack = require('webpack');
const config = require('./webpack.config.js');

// コールバック方式
webpack(config, (err, stats) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(stats.toString({ colors: true }));
});

// Compiler インスタンス方式
const compiler = webpack(config);
compiler.run((err, stats) => {
  // ビルド完了処理
  compiler.close((closeErr) => {
    // コンパイラリソースの解放
  });
});
```

---

## 4. 【STEP1】設定ファイルの作成（webpack.config.js）

> **業務フローでの位置**: ビルドの前準備として、プロジェクトの要件に合わせた設定ファイルを作成・編集するステップです。

### 4.1 設定ファイルの基本構造

`webpack.config.js` は以下の主要項目で構成されます。設定値はJSON Schemaによるバリデーション（`schemas/WebpackOptions.json`）で妥当性が検証されます。

| 設定項目 | 説明 | 必須 |
|---------|------|------|
| `mode` | ビルドモード（'development' / 'production' / 'none'） | 推奨 |
| `entry` | エントリポイント（バンドルの起点） | 推奨 |
| `output` | 出力先（パス、ファイル名、publicPath等） | 推奨 |
| `module` | ローダー設定（ファイル種別ごとの変換ルール） | 任意 |
| `resolve` | モジュール解決設定（エイリアス、拡張子等） | 任意 |
| `plugins` | プラグイン設定（追加機能の有効化） | 任意 |
| `optimization` | 最適化設定（コード分割、Tree Shaking等） | 任意 |
| `devtool` | ソースマップ戦略の選択 | 任意 |
| `target` | ビルドターゲット（'web' / 'node'等） | 任意 |
| `externals` | バンドルから除外する外部依存 | 任意 |

> **注意**: `mode` を設定しない場合、警告（`NoModeWarning`）が表示され、デフォルトで `'production'` が使用されます。

### 4.2 エントリポイントの設定

エントリポイントは、webpackがモジュール依存関係の解析を開始する起点です。

**シングルエントリ：**
```javascript
module.exports = {
  entry: './src/index.js'
};
```

**マルチエントリ：**
```javascript
module.exports = {
  entry: {
    pageA: './src/pages/a.js',
    pageB: './src/pages/b.js',
    pageC: './src/pages/c.js'
  }
};
```

**dependOn による依存関係の指定：**
```javascript
module.exports = {
  entry: {
    'react-vendors': { import: ['react', 'react-dom', 'prop-types'] },
    app: { import: './src/app.js', dependOn: 'react-vendors' },
    page1: { import: './src/page1.js', dependOn: ['app', 'react-vendors'] }
  }
};
```

### 4.3 出力設定

ビルド成果物の出力先とファイル名パターンを設定します。

```javascript
const path = require('path');

module.exports = {
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js',     // エントリチャンク名
    chunkFilename: '[name].[contenthash].js', // 非同期チャンク名
    publicPath: '/assets/',                   // 公開パス
    clean: true                               // ビルド前にdistをクリーン
  }
};
```

### 4.4 ローダー設定（module.rules）

ファイル種別ごとの変換ルールを設定します。

```javascript
module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: 'babel-loader'
      },
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader']
      },
      {
        test: /\.(png|jpg|gif|svg)$/,
        type: 'asset/resource'  // アセットモジュール（webpack 5）
      }
    ]
  }
};
```

### 4.5 設定のバリデーション

webpackは起動時に設定オブジェクトをJSON Schemaで検証します（`lib/validateSchema.js`）。設定値が不正な場合、エラーメッセージとともに該当するスキーマ情報が表示されます。

---

## 5. 【STEP2-3】バンドル実行・コード分割（ビルドの実行・最適化）

> **業務フローでの位置**: 設定ファイルに基づいてビルドを実行し、コード分割や最適化を適用するステップです。

### 5.1 ビルドの実行

1. ターミナルでプロジェクトディレクトリに移動します
2. 以下のコマンドを実行します

```bash
# 本番ビルド
npx webpack --mode production

# 開発ビルド
npx webpack --mode development

# 進捗表示付きビルド
npx webpack --progress
```

3. ビルドが成功すると、`output.path` で指定したディレクトリにバンドルファイルが生成されます
4. エラーがある場合は、エラーメッセージと該当モジュールの情報が表示されます

### 5.2 コード分割（SplitChunksPlugin）

SplitChunksPlugin（`lib/optimize/SplitChunksPlugin.js`）により、共通モジュールの自動分割が行われます。

```javascript
module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'all',           // 全チャンク対象
      minSize: 20000,          // 最小チャンクサイズ（バイト）
      maxSize: 0,              // 最大チャンクサイズ（0=制限なし）
      minChunks: 1,            // 最小共有モジュール数
      cacheGroups: {
        vendors: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendors',
          priority: -10
        },
        default: {
          minChunks: 2,
          priority: -20,
          reuseExistingChunk: true
        }
      }
    }
  }
};
```

> **注意**: `minSize` が `maxSize` より大きい場合、`MinMaxSizeWarning` が表示されます。

### 5.3 動的インポートによる遅延読み込み

`import()` 構文を使用して、モジュールを必要なタイミングで動的に読み込むことができます。

```javascript
// ページ遷移時に動的ロード
const loadPage = (pageName) => {
  return import(`./pages/${pageName}`);
};

// React.lazy による遅延読み込み
const LazyComponent = React.lazy(() => import('./components/Heavy'));
```

### 5.4 Tree Shaking

`mode: 'production'` では、以下のプラグインが自動的に適用され未使用コードが除去されます：
- **SideEffectsFlagPlugin** - 副作用のないモジュールをマーク
- **FlagDependencyUsagePlugin** - エクスポートの使用状況をフラグ付け
- **FlagDependencyExportsPlugin** - エクスポート情報の収集
- **InnerGraphPlugin** - モジュール内変数の使用追跡による精密な除去

### 5.5 ランタイムチャンク分離

RuntimeChunkPlugin（`lib/optimize/RuntimeChunkPlugin.js`）により、webpackのランタイムコードを独立したチャンクに分離できます。

```javascript
module.exports = {
  optimization: {
    runtimeChunk: 'single'  // 単一のランタイムチャンクに分離
  }
};
```

---

## 6. 【STEP3-4】開発モード・HMR（開発効率の向上）

> **業務フローでの位置**: 開発中にファイル変更を検知し、ブラウザを自動更新することで開発効率を向上させるステップです。

### 6.1 ウォッチモード

ファイル変更を監視し、自動的にリビルドを実行します。

```bash
npx webpack --watch
```

プログラマティックAPIでの使用（`lib/Watching.js`）：
```javascript
const compiler = webpack(config);
const watching = compiler.watch(
  { aggregateTimeout: 300 },
  (err, stats) => {
    console.log(stats.toString({ colors: true }));
  }
);
```

### 6.2 Hot Module Replacement（HMR）

HotModuleReplacementPlugin（`lib/HotModuleReplacementPlugin.js`）により、ページ全体をリロードせずにモジュール単位での差分更新が可能です。

```javascript
module.exports = {
  devServer: {
    hot: true
  }
};
```

**アプリケーション側のHMR API（`hot/` ディレクトリ）：**
```javascript
if (module.hot) {
  module.hot.accept('./module', () => {
    // モジュール更新時の処理
  });

  module.hot.dispose((data) => {
    // クリーンアップ処理
  });
}
```

### 6.3 遅延コンパイル（Lazy Compilation）

`experiments.lazyCompilation` を有効にすると、リクエスト時に初めてモジュールをコンパイルします（`hot/lazy-compilation-web.js`）。大規模プロジェクトでの開発時ビルド速度が向上します。

```javascript
module.exports = {
  experiments: {
    lazyCompilation: true
  }
};
```

### 6.4 ソースマップの設定

SourceMapDevToolPlugin（`lib/SourceMapDevToolPlugin.js`）により、デバッグ用のソースマップを生成します。

| devtool 値 | 説明 | 用途 |
|------------|------|------|
| `'eval'` | eval形式、高速 | 開発（高速リビルド重視） |
| `'eval-source-map'` | eval + 高品質ソースマップ | 開発（デバッグ重視） |
| `'source-map'` | 別ファイルの完全なソースマップ | 本番（デバッグ対応） |
| `'hidden-source-map'` | 外部参照なしのソースマップ | 本番（エラー報告用） |
| `false` | ソースマップなし | 本番（最小出力） |

---

## 7. 【STEP4-5】ビルド結果の確認・本番デプロイ（成果物の検証と公開）

> **業務フローでの位置**: ビルド結果の統計情報を確認し、パフォーマンスを検証した上で本番環境にデプロイするステップです。

### 7.1 ビルド統計（Stats）の確認

ビルド完了後、統計情報（`lib/Stats.js`、`lib/stats/StatsFactory.js`）が出力されます。

**テキストレポートの表示：**
```bash
npx webpack --stats verbose
```

**JSON形式での出力：**
```bash
npx webpack --json > stats.json
```

**統計プリセット一覧（`lib/stats/DefaultStatsPresetPlugin.js`）：**

| プリセット | 説明 |
|-----------|------|
| `'errors-only'` | エラー情報のみ出力 |
| `'errors-warnings'` | エラーと警告のみ出力 |
| `'minimal'` | バージョン・タイミング・モジュール数・エラー・警告のみ |
| `'normal'` | 標準的な統計情報（デフォルト） |
| `'detailed'` | 詳細な統計情報 |
| `'verbose'` | 全情報を出力 |
| `'summary'` | バージョン・エラー数・警告数のみ |
| `'none'` | 統計情報なし |

### 7.2 パフォーマンス警告の確認

webpackは以下のパフォーマンス警告を自動的に検出します（`lib/performance/` 配下）：

| 警告 | 説明 | 対処法 |
|------|------|--------|
| `AssetsOverSizeLimitWarning` | アセットが推奨サイズ（244KiB）を超過 | コード分割の実施、不要コードの削除 |
| `EntrypointsOverSizeLimitWarning` | エントリポイントの合計サイズが超過 | エントリの分割、動的インポートの活用 |
| `NoAsyncChunksWarning` | 非同期チャンクが未使用 | 動的インポートによるコード分割の導入 |

```javascript
module.exports = {
  performance: {
    maxAssetSize: 250000,      // アセットサイズ上限（バイト）
    maxEntrypointSize: 250000, // エントリポイントサイズ上限
    hints: 'warning'           // 'warning' | 'error' | false
  }
};
```

### 7.3 マニフェストファイルの生成

ManifestPlugin（`lib/ManifestPlugin.js`）により、ビルド成果物のマッピング情報を `manifest.json` として出力できます。CDNやサーバーサイドレンダリングでのアセット参照に使用します。

### 7.4 本番ビルドの実行

本番環境向けビルドでは、以下の最適化が自動適用されます：

```bash
npx webpack --mode production
```

| 最適化 | 説明 |
|--------|------|
| Tree Shaking | 未使用エクスポートの除去 |
| Scope Hoisting | モジュール連結による実行速度向上 |
| コード圧縮 | terser-webpack-plugin による最小化 |
| 決定的ID | DeterministicModuleIdsPlugin / DeterministicChunkIdsPlugin によるキャッシュ安定化 |
| コンテンツハッシュ | RealContentHashPlugin による出力ファイルのキャッシュバスティング |
| エクスポート名マングリング | MangleExportsPlugin によるバンドルサイズ削減 |

### 7.5 プロファイリング

ProfilingPlugin（`lib/debug/ProfilingPlugin.js`）により、各フェーズの実行時間をChrome DevTools形式で計測できます。

```javascript
const webpack = require('webpack');

module.exports = {
  plugins: [
    new webpack.debug.ProfilingPlugin({
      outputPath: 'events.json'
    })
  ]
};
```

---

## 8. Module Federation（マイクロフロントエンド）

### 8.1 Module Federationの概要

ModuleFederationPlugin（`lib/container/ModuleFederationPlugin.js`）により、複数の独立したビルド間でモジュールを動的に共有するマイクロフロントエンドアーキテクチャを実現します。

構成要素：
- **ホストアプリケーション** - リモートモジュールを消費する側
- **リモートアプリケーション** - モジュールを公開する側
- **共有依存関係** - 複数アプリケーション間で共有するパッケージ（react等）

### 8.2 ホストアプリケーションの設定

```javascript
const { ModuleFederationPlugin } = require('webpack').container;

module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: 'host',
      remotes: {
        'mfe-b': 'mfeB@http://localhost:3001/remoteEntry.js',
        'mfe-c': 'mfeC@http://localhost:3002/remoteEntry.js'
      },
      shared: {
        react: { singleton: true },
        'react-dom': { singleton: true }
      }
    })
  ]
};
```

### 8.3 リモートアプリケーションの設定

```javascript
const { ModuleFederationPlugin } = require('webpack').container;

module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: 'mfeB',
      filename: 'remoteEntry.js',
      exposes: {
        './Component': './src/Component'
      },
      shared: {
        react: { singleton: true }
      }
    })
  ]
};
```

### 8.4 リモートモジュールの使用

```javascript
// ホストアプリケーションからリモートコンポーネントを利用
import ComponentB from 'mfe-b/Component';
import ComponentC from 'mfe-c/Component';

// React.lazy による遅延読み込み
const LazyComponent = React.lazy(() => import('mfe-c/Component2'));
```

> **注意**: 共有モジュール（SharePlugin / ConsumeSharedPlugin / ProvideSharedPlugin）により、reactなどの依存関係はシングルトンとして管理され、バージョン競合を防止します。

---

## 9. アセット管理・CSS対応

### 9.1 アセットモジュール

webpack 5 ではアセットモジュール（`lib/asset/` 配下）により、画像・フォント等のファイルをモジュールとして扱えます。

| アセットタイプ | 説明 |
|-------------|------|
| `asset/resource` | ファイルを出力ディレクトリにコピーし、URLを返す |
| `asset/inline` | ファイルをData URLとしてインライン化 |
| `asset/source` | ファイル内容を文字列として返す |
| `asset` | サイズに応じてresource / inlineを自動選択 |

```javascript
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/,
        type: 'asset',
        parser: {
          dataUrlCondition: {
            maxSize: 8 * 1024  // 8KiB以下はインライン化
          }
        }
      }
    ]
  }
};
```

### 9.2 CSS処理

CSSモジュール（`lib/css/` 配下）により、CSSファイルをモジュールとして処理し、動的なCSS読み込みランタイム（CssLoadingRuntimeModule）を生成します。

```javascript
module.exports = {
  experiments: {
    css: true  // webpack ネイティブCSS対応を有効化
  }
};
```

### 9.3 WebAssembly対応

同期・非同期のWebAssemblyモジュール（`lib/wasm-sync/`、`lib/wasm-async/`）を処理できます。

```javascript
module.exports = {
  experiments: {
    asyncWebAssembly: true  // 非同期WASM対応を有効化
  }
};
```

> **注意**: WebAssemblyモジュールが初期チャンクに含まれている場合、`WebAssemblyInInitialChunkError` が発生します。非同期インポートの使用を推奨します。

---

## 10. プラグインシステム

### 10.1 主要な組込みプラグイン

webpackには多数の組込みプラグインが含まれています。以下は主要なものです：

| プラグイン | 説明 | 使用例 |
|-----------|------|--------|
| DefinePlugin | コンパイル時定数の定義 | 環境変数の注入、条件分岐 |
| ProvidePlugin | モジュールの自動提供 | jQuery等のグローバル変数化 |
| BannerPlugin | バナー（ライセンス情報等）の挿入 | 著作権表示の追加 |
| DotenvPlugin | .envファイルからの環境変数読み込み | 環境設定の注入 |
| EnvironmentPlugin | process.env経由の環境変数注入 | NODE_ENV等の注入 |
| IgnorePlugin | 指定モジュールの除外 | moment.jsのロケール除外 |
| ProgressPlugin | ビルド進捗の表示 | CI/CDでの進捗監視 |
| CleanPlugin | 出力ディレクトリのクリーンアップ | ビルド前の不要ファイル削除 |
| NormalModuleReplacementPlugin | モジュールの置換 | 環境別のモジュール切り替え |
| DllPlugin / DllReferencePlugin | DLLバンドルの生成・参照 | ビルド時間の短縮 |

### 10.2 プラグインの設定方法

```javascript
const webpack = require('webpack');

module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      'process.env.NODE_ENV': JSON.stringify('production'),
      VERSION: JSON.stringify('1.0.0')
    }),
    new webpack.ProvidePlugin({
      $: 'jquery',
      jQuery: 'jquery'
    }),
    new webpack.BannerPlugin({
      banner: '/*! My App - MIT License */'
    }),
    new webpack.IgnorePlugin({
      resourceRegExp: /^\.\/locale$/,
      contextRegExp: /moment$/
    }),
    new webpack.ProgressPlugin()
  ]
};
```

### 10.3 キャッシュ設定

webpackはビルド結果をキャッシュしてリビルド速度を向上させます（`lib/cache/` 配下）。

| キャッシュタイプ | 説明 |
|---------------|------|
| メモリキャッシュ | `MemoryCachePlugin` - ビルド間でメモリにキャッシュ（デフォルト：development） |
| ファイルキャッシュ | `IdleFileCachePlugin` / `PackFileCacheStrategy` - ファイルシステムに永続化 |
| リゾルバキャッシュ | `ResolverCachePlugin` - モジュール解決結果のキャッシュ |

```javascript
module.exports = {
  cache: {
    type: 'filesystem',       // ファイルシステムキャッシュ
    buildDependencies: {
      config: [__filename]    // 設定ファイル変更時にキャッシュ無効化
    }
  }
};
```

---

## 11. 日常業務の流れ

本セクションでは、業務フローに沿った日常業務の流れを説明します。

```
業務フロー概要（再掲）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
【STEP 1】設定ファイル（webpack.config.js）の作成・編集 → 4章参照
    ↓
【STEP 2】webpack コマンドによるビルド実行 → 5章参照
    ↓
【STEP 3】コード分割・最適化の適用 → 5章参照
    ↓
【STEP 4】ビルド結果（Stats）の確認・パフォーマンス検証 → 7章参照
    ↓
【STEP 5】本番向け成果物の確定・デプロイ → 7章参照
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### 11.1 【開発者】STEP1: プロジェクト初期設定

新規プロジェクトの開始時に、webpack設定を準備します。

1. `webpack` と `webpack-cli` をインストール（2章参照）
2. `webpack.config.js` を作成（4章参照）
3. `package.json` の `scripts` にビルドコマンドを追加
4. ローダーの設定（Babel、CSS等）を追加
5. 必要なプラグインを設定

### 11.2 【開発者】STEP2: 日常開発

日常の開発作業では、開発サーバーとHMRを活用します。

1. `npm run dev` で開発サーバーを起動
2. ソースコードを編集すると、HMRにより自動的にブラウザが更新されます
3. エラーが発生した場合は、コンソールに表示されるエラーメッセージを確認します
4. 必要に応じて `webpack --watch` モードも利用可能です

### 11.3 【開発者】STEP3: ビルドと最適化

機能開発が完了したら、ビルドと最適化を実施します。

1. `npm run build` で本番ビルドを実行
2. コード分割の結果をStatsレポートで確認
3. バンドルサイズが大きい場合は、動的インポートによる遅延読み込みを検討
4. パフォーマンス警告がある場合は対処（7.2章参照）

### 11.4 【ビルドエンジニア】STEP4-5: ビルド結果の検証・デプロイ

ビルド成果物を検証し、本番環境にデプロイします。

1. `webpack --stats verbose` でビルド統計を確認
2. パフォーマンスバジェットの遵守を確認（`performance` 設定）
3. マニフェストファイルを利用してアセット参照を管理
4. 必要に応じてプロファイリング結果を確認（`events.json`）
5. 成果物を本番環境にデプロイ

---

## 12. よくある質問と対処法

### 12.1 設定に関するQ&A

**Q: `mode` を設定していないのに警告が出ます**

A: webpackは `mode` オプションが未設定の場合、`NoModeWarning` を表示しデフォルトで `'production'` を使用します。明示的に `mode: 'development'` または `mode: 'production'` を設定してください。

**Q: 設定ファイルのバリデーションエラーが出ます**

A: webpackは `schemas/WebpackOptions.json` に基づいて設定を検証します。エラーメッセージに表示されるプロパティ名とスキーマ情報を確認し、設定値を修正してください。

### 12.2 ビルドに関するQ&A

**Q: ビルド時間が長い**

A: 以下の対策を検討してください：
1. `cache: { type: 'filesystem' }` でファイルキャッシュを有効化
2. `experiments.lazyCompilation` で開発時の遅延コンパイルを有効化
3. DllPlugin による事前ビルドの活用
4. `module.noParse` で解析不要なライブラリをスキップ

**Q: バンドルサイズが大きい**

A: 以下の対策を検討してください：
1. `optimization.splitChunks` でコード分割を有効化
2. 動的インポート（`import()`）による遅延読み込み
3. `externals` で大きなライブラリをバンドルから除外
4. Tree Shaking が効いていない場合、ESモジュール形式のインポートを使用
5. `stats: 'verbose'` でモジュールサイズを確認

**Q: 大文字小文字の警告が出ます**

A: `CaseSensitiveModulesWarning` は、ファイルパスの大文字小文字が一致しない場合に表示されます。macOS（大文字小文字を区別しない）とLinux（区別する）で動作が異なるため、インポートパスの大文字小文字を統一してください。

### 12.3 Module Federationに関するQ&A

**Q: リモートモジュールが読み込めない**

A: 以下を確認してください：
1. リモートアプリケーションが起動しており、`remoteEntry.js` にアクセス可能か
2. `shared` 設定でバージョン要件が一致しているか
3. `singleton: true` 設定が必要なパッケージ（react等）に適用されているか

---

## 13. トラブルシューティング

### 13.1 エラーメッセージと対処法

| エラーメッセージ | 原因 | 対処法 |
|----------------|------|--------|
| `ModuleNotFoundError` | 要求されたモジュールが見つからない | パスの確認、パッケージのインストール、`resolve.alias` の確認 |
| `ModuleBuildError` | ローダー実行時のエラー | ローダーの設定・バージョンの確認、ソースコードの構文エラーの修正 |
| `ModuleParseError` | モジュール解析時のエラー | 適切なローダーの設定（バイナリファイルにはassetモジュールを使用） |
| `HarmonyLinkingError` | ESモジュールのimport/exportリンクエラー | エクスポート名の確認、循環参照の解消 |
| `WebAssemblyInInitialChunkError` | WASMモジュールが初期チャンクに含まれている | 非同期インポート（`import()`）を使用 |
| `ChunkRenderError` | チャンクレンダリング時のエラー | プラグイン設定の確認、最新バージョンへのアップデート |
| `BuildCycleError` | モジュール依存の循環参照 | 循環参照の解消、モジュール構造の見直し |
| `AsyncDependencyToInitialChunkError` | 初期チャンクのオンデマンド読み込み試行 | エントリポイント構成の見直し |

### 13.2 よくあるトラブルと解決方法

**webpack-cli がインストールされていない**

```
CLI for webpack must be installed.
```

→ `npm install --save-dev webpack-cli` を実行してください。

**ファイル変更がウォッチモードで検知されない**

→ ファイル監視のポーリング設定を確認してください：
```javascript
module.exports = {
  watchOptions: {
    poll: 1000,          // ポーリング間隔（ミリ秒）
    aggregateTimeout: 300 // 変更後の再ビルド待機時間
  }
};
```

**キャッシュ関連のエラー（ModuleRestoreError / ModuleStoreError）**

→ キャッシュファイルが破損している可能性があります。`node_modules/.cache/webpack` を削除してリビルドしてください。

**環境が async/await をサポートしない警告**

`EnvironmentNotSupportAsyncWarning` が表示される場合：
```javascript
module.exports = {
  output: {
    environment: {
      arrowFunction: true,
      asyncFunction: true
    }
  }
};
```

### 13.3 サポートへの連絡方法

- **Issue報告**: [https://github.com/webpack/webpack/issues](https://github.com/webpack/webpack/issues)
- **ディスカッション**: [https://github.com/webpack/webpack/discussions](https://github.com/webpack/webpack/discussions)
- **スポンサー**: [https://opencollective.com/webpack](https://opencollective.com/webpack)

---

## 改訂履歴

| 版数 | 改訂日 | 改訂内容 |
|-----|--------|---------|
| 1.0 | 2026-03-01 | 初版作成 |

---

*本マニュアルは、webpack（v5.105.3）のエンドユーザー向け業務運用マニュアルです。*
*システムの更新により、コマンドや設定方法が変更される場合があります。*
