# API設計書

## 概要

本ドキュメントは、webpack（v5.105.3）が提供するNode.jsプログラマティックAPIの設計仕様を定義する。webpackはJavaScriptモジュールバンドラーであり、REST APIではなくNode.jsライブラリとしてのプログラマティックAPIを提供する。本設計書では、メインエントリポイント、Compilerクラス、Compilationクラス、HMR（Hot Module Replacement）API、プラグインAPI、ローダーAPI等の公開インターフェースを網羅的に記載する。

## 共通仕様

### ベースURL

```
該当なし（Node.jsライブラリとしてのプログラマティックAPI）
```

### 利用方法

```javascript
const webpack = require("webpack");
// または
import webpack from "webpack";
```

### 認証方式

該当なし（Node.jsモジュールとして直接呼び出し）

### 共通ヘッダー

該当なし（HTTP APIではない）

### 共通エラーハンドリング

| エラー種別 | 説明 |
| --- | --- |
| `WebpackError` | webpack内部エラーの基底クラス |
| `ValidationError` | 設定バリデーションエラー（schema-utils由来） |
| `AbstractMethodError` | 抽象メソッド未実装エラー |
| `ConcurrentCompilationError` | 同時コンパイル実行エラー |

エラーはコールバックの第一引数として返される。コンパイル中の非致命的エラーは `compilation.errors` 配列に蓄積される。

## API一覧

| カテゴリ | API | 種別 | 説明 |
| --- | --- | --- | --- |
| メインAPI | `webpack(options, callback?)` | 関数 | メインエントリポイント。コンパイラを作成し、オプションでビルドを実行 |
| メインAPI | `webpack.validate(options)` | 関数 | 設定オブジェクトのバリデーション |
| メインAPI | `webpack.validateSchema(schema, options)` | 関数 | JSONスキーマによるバリデーション |
| メインAPI | `webpack.version` | プロパティ | webpackバージョン文字列 |
| Compiler | `compiler.run(callback)` | メソッド | 単一ビルド実行 |
| Compiler | `compiler.watch(watchOptions, handler)` | メソッド | ウォッチモード開始 |
| Compiler | `compiler.close(callback)` | メソッド | コンパイラリソース解放 |
| Compilation | `compilation.addEntry(context, entry, options, callback)` | メソッド | エントリポイント追加 |
| Compilation | `compilation.getStats()` | メソッド | ビルド統計取得 |
| Compilation | `compilation.emitAsset(file, source, assetInfo)` | メソッド | アセット出力 |
| Stats | `stats.toJson(options?)` | メソッド | JSON形式のビルド統計出力 |
| Stats | `stats.toString(options?)` | メソッド | 文字列形式のビルド統計出力 |
| Stats | `stats.hasErrors()` | メソッド | エラー有無確認 |
| Stats | `stats.hasWarnings()` | メソッド | 警告有無確認 |
| MultiCompiler | `multiCompiler.run(callback)` | メソッド | 全コンパイラ実行 |
| MultiCompiler | `multiCompiler.watch(watchOptions, handler)` | メソッド | 全コンパイラウォッチ |
| Watching | `watching.close(callback)` | メソッド | ウォッチ停止 |
| Watching | `watching.invalidate(changedFiles?)` | メソッド | ファイル変更通知 |
| HMR | `module.hot.accept(deps?, callback?)` | メソッド | モジュール更新受け入れ |
| HMR | `module.hot.decline(deps?)` | メソッド | モジュール更新拒否 |
| HMR | `module.hot.dispose(callback)` | メソッド | クリーンアップハンドラ登録 |
| HMR | `module.hot.check(autoApply?)` | メソッド | 更新チェック |
| HMR | `module.hot.apply(options?)` | メソッド | 更新適用 |
| HMR | `module.hot.status()` | メソッド | 現在のHMRステータス取得 |
| CLI | `webpack.cli.getArguments(schema)` | 関数 | CLIフラグ定義取得 |
| プラグイン | `plugin.apply(compiler)` | メソッド | プラグイン適用インターフェース |
| ローダー | `this.callback(err, content, sourceMap?, additionalData?)` | コールバック | ローダー結果返却 |
| ローダー | `this.async()` | メソッド | 非同期ローダー宣言 |

## 各APIエンドポイント定義

### メインAPI

#### 1 webpack()

webpackのメインエントリポイント関数。設定オブジェクトからCompilerまたはMultiCompilerインスタンスを作成し、オプションでビルドを実行する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| モジュール | `require("webpack")` |
| ソースファイル | `lib/webpack.js` |
| エクスポート | デフォルトエクスポート |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| options | `WebpackOptions \| WebpackOptions[]` | ○ | webpack設定オブジェクト。配列の場合はMultiCompilerを返す |
| callback | `(err: Error \| null, stats?: Stats \| MultiStats) => void` | - | コンパイル完了コールバック。指定時はビルド自動開始 |

**戻り値**

```javascript
// 単一設定の場合
const compiler = webpack(config);           // Compiler
const compiler = webpack(config, callback); // Compiler | null

// 配列設定の場合
const multiCompiler = webpack([config1, config2]);           // MultiCompiler
const multiCompiler = webpack([config1, config2], callback); // MultiCompiler | null
```

| 条件 | 戻り値 |
| --- | --- |
| callback なし、単一設定 | `Compiler` |
| callback なし、配列設定 | `MultiCompiler` |
| callback あり、成功 | `Compiler \| MultiCompiler` |
| callback あり、エラー | `null`（エラーはcallbackへ） |

**使用例**

```json
{
  "entry": "./src/index.js",
  "output": {
    "path": "/dist",
    "filename": "bundle.js"
  },
  "mode": "production"
}
```

**レスポンス（コールバック）**

成功時:

```javascript
callback(null, stats)
// stats.toJson() の例:
{
  "hash": "abc123def456",
  "version": "5.105.3",
  "time": 1234,
  "builtAt": 1709312400000,
  "outputPath": "/dist",
  "errors": [],
  "warnings": [],
  "assets": [
    {
      "name": "bundle.js",
      "size": 12345
    }
  ]
}
```

エラー時:

```javascript
callback(error, undefined)
// error: Error オブジェクト
// - message: エラーメッセージ
// - details: 詳細情報（バリデーションエラー時）
```

---

#### 2 webpack.validate()

webpack設定オブジェクトをJSONスキーマに基づいてバリデーションする。不正な設定の場合は `ValidationError` をスローする。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| モジュール | `require("webpack").validate` |
| ソースファイル | `lib/index.js`（遅延読み込み） |
| エクスポート | 名前付きプロパティ |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| options | `WebpackOptions \| WebpackOptions[]` | ○ | バリデーション対象の設定オブジェクト |

**戻り値**

| 条件 | 戻り値 |
| --- | --- |
| バリデーション成功 | `void`（正常終了） |
| バリデーション失敗 | `ValidationError` をスロー |

**使用例**

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

try {
  webpack.validate({
    entry: "./src/index.js",
    output: { path: "/dist", filename: "bundle.js" }
  });
} catch (err) {
  // ValidationError: Invalid configuration object.
  console.error(err.message);
}
```

---

#### 3 webpack.version

webpackの現在のバージョン文字列を返す。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| モジュール | `require("webpack").version` |
| 型 | `string` |
| 値 | `"5.105.3"`（package.jsonから読み込み） |

---

### Compiler API

#### 4 compiler.run()

単一のコンパイルパスを実行する。コンパイル完了後、コールバックにStatsオブジェクトが渡される。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| クラス | `Compiler` |
| ソースファイル | `lib/Compiler.js` |
| 前提条件 | コンパイラが実行中でないこと（`running === false`） |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| callback | `(err: Error \| null, stats?: Stats) => void` | ○ | コンパイル完了コールバック |

**実行フロー**

```
hooks.beforeRun → hooks.run → compile() → hooks.shouldEmit
→ hooks.emit → emitAssets() → hooks.afterEmit
→ hooks.done → hooks.afterDone → callback(null, stats)
```

**レスポンス（コールバック）**

成功時:

```javascript
callback(null, stats)
// stats: Stats オブジェクト
```

エラー時:

```javascript
callback(error)
// ConcurrentCompilationError: 同時実行エラー
// その他の Error: コンパイルエラー
```

---

#### 5 compiler.watch()

ファイルシステムの変更を監視し、変更検出時に自動的に再コンパイルを実行する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| クラス | `Compiler` |
| ソースファイル | `lib/Compiler.js` |
| 戻り値 | `Watching` インスタンス |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| watchOptions | `WatchOptions` | ○ | ウォッチ設定 |
| handler | `(err: Error \| null, stats?: Stats) => void` | ○ | 各コンパイル完了時のコールバック |

**WatchOptions定義**

| フィールド名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| aggregateTimeout | `number` | - | `200` | 変更検出後の待機時間（ミリ秒） |
| ignored | `string \| RegExp \| string[]` | - | - | 監視対象外パターン |
| poll | `boolean \| number` | - | `false` | ポーリング間隔（ミリ秒）。`true`の場合は5007ms |
| followSymlinks | `boolean` | - | `false` | シンボリックリンクの追従 |
| stdin | `boolean` | - | `true` | stdin閉じ時にウォッチ停止 |

**使用例**

```javascript
const compiler = webpack(config);
const watching = compiler.watch(
  { aggregateTimeout: 300, poll: false },
  (err, stats) => {
    if (err) { console.error(err); return; }
    console.log(stats.toString({ colors: true }));
  }
);

// 停止する場合
watching.close((closeErr) => {
  console.log("Watching ended.");
});
```

---

#### 6 compiler.close()

コンパイラのリソースを解放する。ウォッチモードの場合はウォッチを停止し、キャッシュの永続化を行う。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| クラス | `Compiler` |
| ソースファイル | `lib/Compiler.js` |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| callback | `(err?: Error) => void` | ○ | クローズ完了コールバック |

---

#### 7 compiler.getCache()

指定した名前のキャッシュファサードを取得する。プラグインが独自のキャッシュ空間を利用する際に使用する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| クラス | `Compiler` |
| ソースファイル | `lib/Compiler.js` |
| 戻り値 | `CacheFacade` |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| name | `string` | ○ | キャッシュ名前空間 |

---

#### 8 compiler.getInfrastructureLogger()

インフラストラクチャログ用のロガーインスタンスを取得する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| クラス | `Compiler` |
| ソースファイル | `lib/Compiler.js` |
| 戻り値 | `Logger` |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| name | `string \| (() => string)` | ○ | ロガー名 |

---

#### 9 compiler.createChildCompiler()

子コンパイラを作成する。プラグインが追加のコンパイルパスを実行するために使用する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| クラス | `Compiler` |
| ソースファイル | `lib/Compiler.js` |
| 戻り値 | `Compiler` |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| name | `string` | ○ | 子コンパイラ名 |
| outputOptions | `OutputOptions` | ○ | 出力オプション |
| plugins | `WebpackPluginInstance[]` | ○ | 適用するプラグイン配列 |

---

### Compiler Hooks

Compilerは Tapable ベースのフックシステムを提供する。プラグインはこれらのフックに登録してコンパイルプロセスに介入する。

#### フック一覧

| フック名 | 型 | パラメータ | 説明 |
| --- | --- | --- | --- |
| `environment` | `SyncHook` | なし | 環境セットアップ前 |
| `afterEnvironment` | `SyncHook` | なし | 環境セットアップ後 |
| `initialize` | `SyncHook` | なし | プラグイン初期化後 |
| `beforeRun` | `AsyncSeriesHook` | `compiler` | run実行前 |
| `run` | `AsyncSeriesHook` | `compiler` | run実行開始 |
| `beforeCompile` | `AsyncSeriesHook` | `params` | コンパイル開始前 |
| `compile` | `SyncHook` | `params` | コンパイル開始 |
| `thisCompilation` | `SyncHook` | `compilation, params` | Compilation作成直後 |
| `compilation` | `SyncHook` | `compilation, params` | Compilation作成後 |
| `make` | `AsyncParallelHook` | `compilation` | モジュールグラフ構築 |
| `finishMake` | `AsyncSeriesHook` | `compilation` | モジュールグラフ構築完了 |
| `afterCompile` | `AsyncSeriesHook` | `compilation` | コンパイル完了後 |
| `shouldEmit` | `SyncBailHook` | `compilation` | アセット出力判定 |
| `emit` | `AsyncSeriesHook` | `compilation` | アセット出力前 |
| `assetEmitted` | `AsyncSeriesHook` | `file, info` | 個別アセット出力後 |
| `afterEmit` | `AsyncSeriesHook` | `compilation` | 全アセット出力後 |
| `done` | `AsyncSeriesHook` | `stats` | コンパイル完了 |
| `afterDone` | `SyncHook` | `stats` | doneフック完了後 |
| `watchRun` | `AsyncSeriesHook` | `compiler` | ウォッチモードでの再コンパイル開始 |
| `invalid` | `SyncHook` | `fileName, changeTime` | 監視ファイル変更検出 |
| `watchClose` | `SyncHook` | なし | ウォッチモード終了 |
| `shutdown` | `AsyncSeriesHook` | なし | コンパイラシャットダウン |
| `normalModuleFactory` | `SyncHook` | `normalModuleFactory` | NormalModuleFactory作成時 |
| `contextModuleFactory` | `SyncHook` | `contextModuleFactory` | ContextModuleFactory作成時 |
| `infrastructureLog` | `SyncBailHook` | `name, type, args` | インフラログ出力 |

**フック登録方法**

```javascript
// 同期フック
compiler.hooks.compile.tap("PluginName", (params) => { /* ... */ });

// 非同期フック（コールバック方式）
compiler.hooks.run.tapAsync("PluginName", (compiler, callback) => {
  // 処理完了後
  callback();
});

// 非同期フック（Promise方式）
compiler.hooks.run.tapPromise("PluginName", (compiler) => {
  return new Promise((resolve) => { resolve(); });
});
```

---

### Compilation API

#### 10 compilation.addEntry()

コンパイルにエントリポイントを追加する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| クラス | `Compilation` |
| ソースファイル | `lib/Compilation.js` |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| context | `string` | ○ | コンテキストディレクトリ |
| entry | `Dependency` | ○ | エントリ依存関係 |
| optionsOrName | `EntryOptions \| string` | ○ | エントリオプションまたは名前 |
| callback | `(err?: Error) => void` | ○ | 完了コールバック |

---

#### 11 compilation.emitAsset()

コンパイル結果にアセットを追加する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| クラス | `Compilation` |
| ソースファイル | `lib/Compilation.js` |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| file | `string` | ○ | アセットファイル名 |
| source | `Source` | ○ | アセットコンテンツ（webpack-sources由来） |
| assetInfo | `AssetInfo` | - | アセットメタデータ |

**AssetInfo定義**

| フィールド名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| immutable | `boolean` | - | 永続キャッシュ可能 |
| minimized | `boolean` | - | 最小化済み |
| sourceFilename | `string` | - | 元のファイル名 |
| development | `boolean` | - | 開発用アセット |
| hotModuleReplacement | `boolean` | - | HMRアセット |
| related | `Record<string, string[]>` | - | 関連アセット |

---

#### 12 compilation.getStats()

現在のコンパイルのStatsオブジェクトを取得する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| クラス | `Compilation` |
| ソースファイル | `lib/Compilation.js` |
| 戻り値 | `Stats` |

---

### Compilation Hooks

Compilationも Tapable ベースのフックシステムを持つ。

#### 主要フック一覧

| フック名 | 型 | 説明 |
| --- | --- | --- |
| `buildModule` | `SyncHook` | モジュールビルド開始 |
| `succeedModule` | `SyncHook` | モジュールビルド成功 |
| `failedModule` | `SyncHook` | モジュールビルド失敗 |
| `finishModules` | `AsyncSeriesHook` | 全モジュール処理完了 |
| `seal` | `SyncHook` | コンパイルシール（最適化開始） |
| `optimize` | `SyncHook` | 最適化開始 |
| `optimizeModules` | `SyncBailHook` | モジュール最適化 |
| `optimizeChunks` | `SyncBailHook` | チャンク最適化 |
| `optimizeTree` | `AsyncSeriesHook` | ツリー最適化 |
| `optimizeChunkModules` | `AsyncSeriesBailHook` | チャンクモジュール最適化 |
| `processAssets` | `AsyncSeriesHook` | アセット加工（ステージ別） |
| `afterProcessAssets` | `SyncHook` | アセット加工完了 |
| `beforeChunkIds` | `SyncHook` | チャンクID割り当て前 |
| `chunkIds` | `SyncHook` | チャンクID割り当て |
| `beforeModuleIds` | `SyncHook` | モジュールID割り当て前 |
| `moduleIds` | `SyncHook` | モジュールID割り当て |
| `beforeHash` | `SyncHook` | ハッシュ計算前 |
| `afterHash` | `SyncHook` | ハッシュ計算後 |
| `contentHash` | `SyncHook` | コンテンツハッシュ計算 |
| `record` | `SyncHook` | レコード保存 |
| `addEntry` | `SyncHook` | エントリ追加時 |
| `succeedEntry` | `SyncHook` | エントリ追加成功 |
| `failedEntry` | `SyncHook` | エントリ追加失敗 |

**processAssetsステージ定数**

```javascript
Compilation.PROCESS_ASSETS_STAGE_ADDITIONAL      // -2000: 追加アセット
Compilation.PROCESS_ASSETS_STAGE_PRE_PROCESS     // -1000: 前処理
Compilation.PROCESS_ASSETS_STAGE_DERIVED          //  -200: 派生アセット
Compilation.PROCESS_ASSETS_STAGE_ADDITIONS        //  -100: 追加コンテンツ
Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE         //   100: 最適化
Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE_COUNT   //  -100: 最適化カウント
Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE_COMPAT  //  -100: 互換性最適化
Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE_SIZE    //   200: サイズ最適化
Compilation.PROCESS_ASSETS_STAGE_DEV_TOOLING      //   300: 開発ツール
Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE_INLINE  //   700: インライン最適化
Compilation.PROCESS_ASSETS_STAGE_SUMMARIZE        //  1000: サマリー
Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE_HASH    //  2500: ハッシュ最適化
Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE_TRANSFER// 30000: 転送最適化
Compilation.PROCESS_ASSETS_STAGE_ANALYSE          // 40000: 分析
Compilation.PROCESS_ASSETS_STAGE_REPORT           // 50000: レポート
```

---

### Stats API

#### 13 stats.toJson()

ビルド統計情報をJSON形式で取得する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| クラス | `Stats` |
| ソースファイル | `lib/Stats.js` |
| 戻り値 | `StatsCompilation` |

**パラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| options | `StatsOptions \| string` | - | `{}` | 統計オプション。プリセット文字列も可（`"normal"`, `"verbose"`, `"errors-only"`等） |

**レスポンス**

```json
{
  "hash": "abc123def456",
  "version": "5.105.3",
  "time": 1234,
  "builtAt": 1709312400000,
  "publicPath": "auto",
  "outputPath": "/dist",
  "assets": [
    {
      "type": "asset",
      "name": "bundle.js",
      "size": 12345,
      "emitted": true,
      "info": {
        "minimized": true
      }
    }
  ],
  "chunks": [],
  "modules": [],
  "entrypoints": {},
  "errors": [],
  "errorsCount": 0,
  "warnings": [],
  "warningsCount": 0
}
```

---

#### 14 stats.toString()

ビルド統計情報を文字列形式で取得する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| クラス | `Stats` |
| ソースファイル | `lib/Stats.js` |
| 戻り値 | `string` |

**パラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| options | `StatsOptions \| string` | - | `{}` | 統計オプション |

---

#### 15 stats.hasErrors()

コンパイル中にエラーが発生したかどうかを返す。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| クラス | `Stats` |
| 戻り値 | `boolean` |

---

#### 16 stats.hasWarnings()

コンパイル中に警告が発生したかどうかを返す。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| クラス | `Stats` |
| 戻り値 | `boolean` |

---

### MultiCompiler API

#### 17 MultiCompiler

複数の設定を同時にコンパイルする。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| クラス | `MultiCompiler` |
| ソースファイル | `lib/MultiCompiler.js` |
| 生成方法 | `webpack([config1, config2])` |

**コンストラクタパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| compilers | `Compiler[] \| Record<string, Compiler>` | ○ | 子コンパイラ配列 |
| options | `MultiCompilerOptions` | - | マルチコンパイラオプション |

**MultiCompilerOptions定義**

| フィールド名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| parallelism | `number` | - | `Infinity` | 最大同時コンパイル数 |

**メソッド**

| メソッド名 | シグネチャ | 説明 |
| --- | --- | --- |
| `run` | `(callback: (err, stats: MultiStats) => void) => void` | 全コンパイラ実行 |
| `watch` | `(watchOptions, handler) => MultiWatching` | 全コンパイラウォッチ |
| `close` | `(callback: (err?) => void) => void` | 全コンパイラクローズ |
| `setDependencies` | `(compiler, dependencies: string[]) => void` | 依存関係設定 |

**プロパティ**

| プロパティ名 | 型 | 説明 |
| --- | --- | --- |
| `compilers` | `Compiler[]` | 子コンパイラ配列 |
| `running` | `boolean` | 実行中フラグ |
| `hooks.done` | `SyncHook<MultiStats>` | 全コンパイル完了 |

---

### Watching API

#### 18 Watching

ファイルウォッチを管理する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| クラス | `Watching` |
| ソースファイル | `lib/Watching.js` |
| 生成方法 | `compiler.watch(watchOptions, handler)` |

**メソッド**

| メソッド名 | シグネチャ | 説明 |
| --- | --- | --- |
| `close` | `(callback: () => void) => void` | ウォッチ停止 |
| `pause` | `() => void` | ウォッチ一時停止 |
| `resume` | `() => void` | ウォッチ再開 |
| `suspend` | `() => void` | 全アクティビティ停止 |
| `invalidate` | `(changedFiles?: Iterable<string>) => void` | 手動でファイル変更通知 |

---

### Hot Module Replacement (HMR) API

#### 19 module.hot.accept()

モジュールの更新を受け入れる。自身または指定した依存モジュールのHMR更新を処理する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| コンテキスト | ブラウザ/Node.jsランタイム |
| ソースファイル | `hot/dev-server.js`, `lib/hmr/HotModuleReplacement.runtime.js` |
| 前提条件 | `HotModuleReplacementPlugin` 有効 |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| dependencies | `string \| string[]` | - | 受け入れ対象の依存モジュールパス。省略時は自モジュール |
| callback | `(outdatedDependencies?: string[]) => void` | - | 更新時のコールバック |
| errorHandler | `(err: Error, context: {moduleId, dependencyId}) => void` | - | エラーハンドラ |

**使用例**

```javascript
// 自モジュールの更新を受け入れ
if (module.hot) {
  module.hot.accept();
}

// 特定の依存モジュールの更新を受け入れ
if (module.hot) {
  module.hot.accept("./dependency", () => {
    // 依存モジュールが更新された時の処理
  });
}

// 複数の依存モジュール
if (module.hot) {
  module.hot.accept(["./dep1", "./dep2"], () => {
    // いずれかが更新された時の処理
  });
}
```

---

#### 20 module.hot.decline()

モジュールの更新を拒否する。このモジュールまたは指定した依存に更新がある場合、更新は失敗する。

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| dependencies | `string \| string[]` | - | 拒否対象。省略時は自モジュール |

---

#### 21 module.hot.dispose() / addDisposeHandler()

モジュールが置き換えられる際のクリーンアップハンドラを登録する。

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| callback | `(data: object) => void` | ○ | クリーンアップコールバック。`data`は次のモジュールバージョンに引き継がれる |

**使用例**

```javascript
if (module.hot) {
  module.hot.dispose((data) => {
    // 状態を保存して次のバージョンに引き継ぐ
    data.savedState = currentState;
    // リソースのクリーンアップ
    clearInterval(timer);
  });
}
```

---

#### 22 module.hot.check()

サーバーに更新があるかチェックする。

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| autoApply | `boolean \| ApplyOptions` | - | `true`の場合、自動的に更新を適用 |

**戻り値**: `Promise<ModuleId[] | null>`

- 更新がある場合: 更新されたモジュールID配列
- 更新がない場合: `null`

---

#### 23 module.hot.apply()

`check()`で検出された更新を適用する。

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| options | `ApplyOptions` | - | 適用オプション |

**ApplyOptions定義**

| フィールド名 | 型 | 説明 |
| --- | --- | --- |
| ignoreUnaccepted | `boolean` | 受け入れられない更新を無視 |
| ignoreDeclined | `boolean` | 拒否された更新を無視 |
| ignoreErrored | `boolean` | エラーのある更新を無視 |
| onDeclined | `(info) => void` | 拒否時コールバック |
| onUnaccepted | `(info) => void` | 未受け入れ時コールバック |
| onAccepted | `(info) => void` | 受け入れ時コールバック |
| onDisposed | `(info) => void` | 破棄時コールバック |
| onErrored | `(info) => void` | エラー時コールバック |

**戻り値**: `Promise<ModuleId[]>`

---

#### 24 module.hot.status()

HMRプロセスの現在のステータスを返す。

**戻り値**: `string`

| ステータス | 説明 |
| --- | --- |
| `"idle"` | 更新待ち |
| `"check"` | 更新チェック中 |
| `"prepare"` | 更新準備中 |
| `"ready"` | 更新適用可能 |
| `"dispose"` | 旧モジュール破棄中 |
| `"apply"` | 更新適用中 |
| `"abort"` | 更新中断 |
| `"fail"` | 更新失敗 |

---

#### 25 module.hot.addStatusHandler() / removeStatusHandler()

HMRステータス変更時のリスナーを管理する。

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| callback | `(status: string) => void` | ○ | ステータス変更コールバック |

---

### プラグインAPI

#### 26 Plugin Interface

webpackプラグインが実装すべきインターフェース。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| インターフェース | `WebpackPluginInstance` |
| 必須メソッド | `apply(compiler: Compiler): void` |

**プラグイン実装パターン**

```javascript
class MyPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap("MyPlugin", (compilation) => {
      compilation.hooks.processAssets.tap(
        {
          name: "MyPlugin",
          stage: webpack.Compilation.PROCESS_ASSETS_STAGE_SUMMARIZE
        },
        (assets) => {
          // アセットの操作
        }
      );
    });
  }
}
```

**Tapableフックタイプ**

| フック型 | 実行方式 | 戻り値 | 用途 |
| --- | --- | --- | --- |
| `SyncHook` | 同期・順次 | なし | 通知 |
| `SyncBailHook` | 同期・中断可 | truthy値で中断 | 判定 |
| `SyncWaterfallHook` | 同期・連鎖 | 次のハンドラへ渡される | 変換 |
| `AsyncSeriesHook` | 非同期・順次 | なし | 非同期処理 |
| `AsyncSeriesBailHook` | 非同期・中断可 | truthy値で中断 | 非同期判定 |
| `AsyncParallelHook` | 非同期・並列 | なし | 並列処理 |

**登録メソッド**

| メソッド | 説明 |
| --- | --- |
| `hook.tap(name, handler)` | 同期ハンドラ登録 |
| `hook.tapAsync(name, handler)` | 非同期ハンドラ登録（コールバック方式） |
| `hook.tapPromise(name, handler)` | 非同期ハンドラ登録（Promise方式） |

---

### ローダーAPI

#### 27 Loader Context

webpackローダーが使用可能なコンテキストオブジェクト。ローダー関数内で `this` として参照される。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| 型定義 | `declarations/LoaderContext.d.ts` |
| 利用場面 | ローダー関数内の `this` コンテキスト |

**主要プロパティ**

| プロパティ名 | 型 | 説明 |
| --- | --- | --- |
| `version` | `number` | ローダーAPIバージョン（`2`） |
| `context` | `string` | モジュールのディレクトリ |
| `rootContext` | `string` | プロジェクトルート |
| `resourcePath` | `string` | リソースファイルパス |
| `resourceQuery` | `string` | リソースのクエリ文字列 |
| `mode` | `"development" \| "production" \| "none"` | ビルドモード |
| `sourceMap` | `boolean` | ソースマップ生成有無 |
| `data` | `any` | pitchフェーズからのデータ |

**主要メソッド**

| メソッド名 | シグネチャ | 説明 |
| --- | --- | --- |
| `getOptions` | `(schema?) => OptionsType` | ローダーオプション取得 |
| `getLogger` | `(name?) => Logger` | ロガー取得 |
| `resolve` | `(context, request, callback) => void` | モジュール解決 |
| `getResolve` | `(options?) => ResolveFunction` | カスタムリゾルバ取得 |
| `emitFile` | `(name, content, sourceMap?, assetInfo?) => void` | ファイル出力 |
| `emitWarning` | `(warning: Error) => void` | 警告追加 |
| `emitError` | `(error: Error) => void` | エラー追加 |
| `addDependency` | `(file: string) => void` | ファイル依存追加 |
| `addContextDependency` | `(context: string) => void` | ディレクトリ依存追加 |
| `addMissingDependency` | `(file: string) => void` | 欠落ファイル依存追加 |
| `addBuildDependency` | `(dep: string) => void` | ビルド依存追加 |
| `async` | `() => WebpackLoaderContextCallback` | 非同期モード宣言 |
| `cacheable` | `(flag?: boolean) => void` | キャッシュ可否設定 |
| `clearDependencies` | `() => void` | 全依存クリア |

**ローダー関数シグネチャ**

```javascript
// 同期ローダー
module.exports = function(content, sourceMap, additionalData) {
  return transformedContent;
};

// 非同期ローダー
module.exports = function(content, sourceMap, additionalData) {
  const callback = this.async();
  asyncOperation(content, (err, result) => {
    callback(err, result, sourceMap, additionalData);
  });
};

// Pitchローダー
module.exports.pitch = function(remainingRequest, precedingRequest, data) {
  // pitchフェーズの処理
};
```

---

### CLI API

#### 28 webpack.cli.getArguments()

JSONスキーマからCLI引数定義を生成する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| モジュール | `require("webpack").cli` |
| ソースファイル | `lib/cli.js` |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| schema | `object` | ○ | JSONスキーマ（WebpackOptions.json等） |

**戻り値**: `Record<string, Argument>`

**Argument定義**

| フィールド名 | 型 | 説明 |
| --- | --- | --- |
| description | `string` | 引数の説明 |
| simpleType | `"string" \| "number" \| "boolean"` | 簡略型 |
| multiple | `boolean` | 複数値許可 |
| configs | `ArgumentConfig[]` | 設定マッピング |

**サポートされる引数型**

| 型 | 説明 |
| --- | --- |
| `"enum"` | 列挙値 |
| `"string"` | 文字列値 |
| `"path"` | ファイルパス |
| `"number"` | 数値 |
| `"boolean"` | ブール値 |
| `"RegExp"` | 正規表現 |
| `"reset"` | デフォルトへリセット |

---

### エクスポートされるプラグイン・クラス一覧

`require("webpack")` から利用可能な主要エクスポート:

#### コアクラス

| エクスポート名 | ソースファイル | 説明 |
| --- | --- | --- |
| `Compiler` | `lib/Compiler.js` | メインコンパイラ |
| `Compilation` | `lib/Compilation.js` | コンパイル結果 |
| `MultiCompiler` | `lib/MultiCompiler.js` | マルチコンパイラ |
| `Module` | `lib/Module.js` | モジュール基底クラス |
| `NormalModule` | `lib/NormalModule.js` | 通常モジュール |
| `ExternalModule` | `lib/ExternalModule.js` | 外部モジュール |
| `Chunk` | `lib/Chunk.js` | チャンク |
| `ChunkGraph` | `lib/ChunkGraph.js` | チャンクグラフ |
| `ModuleGraph` | `lib/ModuleGraph.js` | モジュールグラフ |
| `Stats` | `lib/Stats.js` | ビルド統計 |
| `Dependency` | `lib/Dependency.js` | 依存関係基底クラス |
| `Generator` | `lib/Generator.js` | コード生成基底クラス |
| `Parser` | `lib/Parser.js` | パーサー基底クラス |
| `Template` | `lib/Template.js` | テンプレート |
| `RuntimeModule` | `lib/RuntimeModule.js` | ランタイムモジュール |
| `RuntimeGlobals` | `lib/RuntimeGlobals.js` | ランタイムグローバル定数 |

#### ビルトインプラグイン

| エクスポート名 | 説明 |
| --- | --- |
| `BannerPlugin` | バンドルにバナーコメント追加 |
| `CleanPlugin` | 出力ディレクトリクリーン |
| `DefinePlugin` | グローバル定数定義 |
| `DllPlugin` | DLLバンドル作成 |
| `DllReferencePlugin` | DLLバンドル参照 |
| `DotenvPlugin` | `.env`ファイル読み込み |
| `DynamicEntryPlugin` | 動的エントリ |
| `EntryPlugin` | エントリポイント追加 |
| `EnvironmentPlugin` | 環境変数参照 |
| `EvalDevToolModulePlugin` | eval devtool |
| `EvalSourceMapDevToolPlugin` | eval-source-map devtool |
| `ExternalsPlugin` | 外部モジュール設定 |
| `HotModuleReplacementPlugin` | HMR有効化 |
| `IgnorePlugin` | モジュール無視 |
| `LoaderOptionsPlugin` | ローダーオプション設定 |
| `ManifestPlugin` | マニフェスト生成 |
| `NoEmitOnErrorsPlugin` | エラー時出力抑制 |
| `NormalModuleReplacementPlugin` | モジュール置換 |
| `PrefetchPlugin` | モジュールプリフェッチ |
| `ProgressPlugin` | ビルド進捗表示 |
| `ProvidePlugin` | グローバル変数プロビジョン |
| `SourceMapDevToolPlugin` | ソースマップ生成 |
| `WatchIgnorePlugin` | ウォッチ対象除外 |

#### 名前空間エクスポート

| 名前空間 | 主要エクスポート | 説明 |
| --- | --- | --- |
| `webpack.optimize` | `SplitChunksPlugin`, `ModuleConcatenationPlugin`, `LimitChunkCountPlugin`, `MinChunkSizePlugin` | 最適化プラグイン |
| `webpack.ids` | `DeterministicModuleIdsPlugin`, `DeterministicChunkIdsPlugin`, `NamedModuleIdsPlugin`, `NamedChunkIdsPlugin` | ID割り当てプラグイン |
| `webpack.javascript` | `JavascriptModulesPlugin`, `JavascriptParser`, `EnableChunkLoadingPlugin` | JavaScript処理 |
| `webpack.container` | `ModuleFederationPlugin`, `ContainerPlugin`, `ContainerReferencePlugin` | Module Federation |
| `webpack.sharing` | `SharePlugin`, `ProvideSharedPlugin`, `ConsumeSharedPlugin` | 共有モジュール |
| `webpack.web` | `JsonpTemplatePlugin`, `FetchCompileWasmPlugin`, `CssLoadingRuntimeModule` | Webターゲット |
| `webpack.node` | `NodeEnvironmentPlugin`, `NodeTargetPlugin`, `NodeTemplatePlugin` | Node.jsターゲット |
| `webpack.wasm` | `AsyncWebAssemblyModulesPlugin`, `EnableWasmLoadingPlugin` | WebAssembly |
| `webpack.css` | `CssModulesPlugin` | CSS処理 |
| `webpack.library` | `EnableLibraryPlugin`, `AbstractLibraryPlugin` | ライブラリ出力 |
| `webpack.config` | `getNormalizedWebpackOptions`, `applyWebpackOptionsDefaults` | 設定処理 |
| `webpack.util` | `createHash`, `comparators`, `runtime`, `serialization`, `cleverMerge`, `LazySet` | ユーティリティ |
| `webpack.sources` | （webpack-sourcesパッケージ） | ソース操作 |
| `webpack.experiments.schemes` | `HttpUriPlugin`, `VirtualUrlPlugin` | 実験的スキーム |

---

### 設定API（Configuration Schema）

webpack設定オブジェクトの主要プロパティ:

| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `entry` | `string \| string[] \| object \| function` | エントリポイント |
| `output` | `OutputOptions` | 出力設定 |
| `module` | `ModuleOptions` | モジュール処理ルール |
| `resolve` | `ResolveOptions` | モジュール解決設定 |
| `resolveLoader` | `ResolveOptions` | ローダー解決設定 |
| `plugins` | `WebpackPluginInstance[]` | プラグイン配列 |
| `mode` | `"development" \| "production" \| "none"` | ビルドモード |
| `devtool` | `string \| false` | ソースマップ設定 |
| `target` | `string \| string[] \| false` | ターゲット環境 |
| `context` | `string` | ベースディレクトリ |
| `externals` | `ExternalItem \| ExternalItem[]` | 外部モジュール定義 |
| `performance` | `PerformanceOptions \| false` | パフォーマンス設定 |
| `optimization` | `OptimizationOptions` | 最適化設定 |
| `cache` | `boolean \| CacheOptions` | キャッシュ設定 |
| `stats` | `StatsOptions \| string \| boolean` | 統計出力設定 |
| `watch` | `boolean` | ウォッチモード |
| `watchOptions` | `WatchOptions` | ウォッチ設定 |
| `experiments` | `ExperimentsOptions` | 実験的機能 |
| `infrastructureLogging` | `InfrastructureLoggingOptions` | インフラログ設定 |
| `bail` | `boolean` | 最初のエラーで中断 |
| `dependencies` | `string[]` | マルチコンパイラ依存関係 |

## 備考

- webpackはHTTP APIを提供するWebアプリケーションではなく、Node.jsのプログラマティックAPIとして動作するモジュールバンドラーである
- 全てのフックはtapableライブラリに基づいており、`tap`/`tapAsync`/`tapPromise`メソッドで登録する
- 非同期操作はコールバックパターンを主に使用する（一部Promise対応）
- ファイルシステムはプラガブルで、`InputFileSystem`/`OutputFileSystem`/`WatchFileSystem`インターフェースを実装することで差し替え可能
- webpack 6で非推奨APIの削除が予定されている（`WebpackOptionsDefaulter`, `LibraryTemplatePlugin`, `SingleEntryPlugin`等）
- 設定の全オプションは`schemas/WebpackOptions.json`のJSONスキーマで定義されている
