webpack-plugin-authoring

dot-skills Webpack 5 プラグインのベストプラクティス

正確で高パフォーマンスな webpack 5 プラグインを作成するための包括的なガイドです。8 つのカテゴリにわたる 44 のルール（hook 8 件、asset 7 件、cache 5 件、life 5 件、schema 4 件、diag 5 件、perf 5 件、compat 5 件）を、作成時のライフサイクルに沿って並べています。まずフックの選択を土台とし、次にアセットの操作、キャッシュとウォッチモードの正確性、ライフサイクルの健全性、ユーザー向けの事項（スキーマ検証、エラー報告）、パフォーマンス、パッケージングへと進みます。

パターンは、webpack/webpack、webpack-contrib のプラグインスイート（mini-css-extract、terser、compression、copy、css-minimizer）、および vercel/next.js における Next.js の webpack 統合から導き出されています。

適用するタイミング

以下の場合に、これらのルールを参照してください。

• 新しいプラグインを作成するとき（apply(compiler) の定義、タップするフックの選択）
• 正確性やパフォーマンスの観点から既存のプラグインコードをレビューするとき
• 「プラグインの出力が表示されないのはなぜか」をデバッグするとき（通常、フックまたはステージの不一致が原因です）
• アセット操作ロジック（processAssets、emitAsset、updateAsset）を追加するとき
• ウォッチモードの古い状態や永続キャッシュの汚染を修正するとき
• プラグインを webpack 4 から webpack 5 に移行するとき（または両方をサポートするとき）
• プラグインを npm に公開するとき（エクスポート形式、peerDependencies、スキーマ）

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	フックの選択とタップのパターン	CRITICAL	hook-
2	アセットパイプライン	CRITICAL	asset-
3	キャッシュとウォッチモード	HIGH	cache-
4	プラグインのライフサイクルと状態	HIGH	life-
5	スキーマとオプションの検証	MEDIUM-HIGH	schema-
6	エラー、警告、ログ	MEDIUM-HIGH	diag-
7	パフォーマンスと並列処理	MEDIUM	perf-
8	互換性とパッケージング	LOW-MEDIUM	compat-

クイックリファレンス

1. フックの選択とタップのパターン（CRITICAL）

• hook-tap-method-matches-hook-type — tap／tapAsync／tapPromise をフックの Sync／Async タイプに合わせます
• hook-thiscompilation-vs-compilation — 子コンパイルをスキップするには thisCompilation を使います
• hook-process-assets-stage — 変更内容に適した PROCESS_ASSETS_STAGE_* を選びます
• hook-prefer-process-assets-over-emit — emit ではなく processAssets で変更します
• hook-bail-hook-return-semantics — 意図的に処理を停止する場合を除き、bail フックから undefined を返します
• hook-tap-once-not-per-compilation — コンパイラーフックはコンパイル用フック内ではなく、apply で一度だけ登録します
• hook-name-matches-class-name — クラス名と同じ、安定したタップ名を使います
• hook-normal-module-factory-stages — 適切な解決ステージ（beforeResolve、resolve、afterResolve）で normalModuleFactory をタップします

2. アセットパイプライン（CRITICAL）

• asset-emit-asset-not-direct-assignment — compilation.assets[name] = ... ではなく、emitAsset／updateAsset を使用します
• asset-source-from-compiler-webpack — ソースクラスは compiler.webpack.sources からインポートします
• asset-preserve-source-maps — ソースマップを保持するため、SourceMapSource／ReplaceSource を使用します
• asset-set-info-metadata — 出力時に info.immutable、info.contenthash、info.related を設定します
• asset-content-hash-via-output-options — ハッシュには、ハードコードした md5 ではなく、compilation.outputOptions.hashFunction を使用します
• asset-delete-then-emit-loses-info — 移動には renameAsset を使用します。deleteAsset と emitAsset の組み合わせではチャンク参照が切断されます
• asset-buffer-not-source-for-binary — バイナリアセットには source() ではなく buffer() を使用します

3. キャッシュとウォッチモード（HIGH）

• cache-add-file-dependencies — 読み込んだファイルを compilation.fileDependencies に追加します
• cache-context-dependencies-for-directories — ディレクトリを走査する場合は contextDependencies を使用します
• cache-missing-dependencies-for-optional-files — 存在しないことを確認したパスを missingDependencies に追加します
• cache-build-dependencies-for-persistent-cache — 永続キャッシュの無効化に備え、buildDependencies を宣言します
• cache-use-input-file-system — Node の fs ではなく、compiler.inputFileSystem 経由で読み込みます

4. プラグインのライフサイクルと状態（HIGH）

• life-constructor-stores-options-only — コンストラクターでは検証と保存のみを行い、副作用は apply() で発生させます
• life-no-mutable-state-across-builds — ローカルの const または WeakMap を使い、変更可能な状態をコンパイルごとに分離します
• life-multi-compiler-isolation — コンパイラーごとにプラグインインスタンスを1つ使用するか、WeakMap<Compiler, T> を使用します
• life-cleanup-in-shutdown-hook — compiler.hooks.shutdown でワーカー、ウォッチャー、ファイルディスクリプターをクリーンアップします
• life-defensively-copy-user-options — ユーザーのオプションオブジェクトは変更しないでください

5. スキーマとオプションの検証（MEDIUM-HIGH）

• schema-validate-with-schema-utils — schema-utils.validate() と JSON Schema を使って検証します
• schema-name-and-base-data-path — エラーメッセージをたどりやすくするため、name と baseDataPath を設定します
• schema-additional-properties-false — タイプミスを検出するため、すべてのオブジェクトに additionalProperties: false を設定します
• schema-tap-into-validate-hook — フィールド間の検証は compiler.hooks.validate に委ねます（5.106+）

6. エラー、警告、ロギング（中〜高）

• diag-push-webpack-error-not-throw — WebpackError をスローせずに compilation.errors に追加します
• diag-use-compilation-get-logger — console ではなく、compilation.getLogger('Plugin') を使ってログを記録します
• diag-attach-loc-to-errors — IDE から該当箇所をクリックして移動できるよう、エラーに loc と module を設定します
• diag-warnings-vs-errors-exit-codes — エラーはビルドを失敗させますが、警告は失敗させません。意図して選択します
• diag-progress-reporting — context.reportProgress で進捗を報告します（context: true で有効化します）

7. パフォーマンスと並列処理（中）

• perf-jest-worker-for-cpu-bound-work — CPU 負荷の高い処理を jest-worker プールに委譲します
• perf-cache-results-with-compilation-cache — compilation.getCache(name).providePromise でコストの高い処理の結果をキャッシュします
• perf-traverse-chunks-not-modules — 可能な場合は compilation.modules ではなく compilation.chunks を反復処理します
• perf-avoid-source-toString-in-hot-paths — 調査するだけのアセットには source().toString() を使わないようにします
• perf-respect-experimental-options — experiments.cacheUnaffected / incremental を尊重します

8. 互換性とパッケージング（低〜中）

• compat-webpack-as-peer-dependency — webpack は dependencies ではなく peerDependencies として宣言します
• compat-use-compiler-webpack-namespace — require('webpack') ではなく compiler.webpack.* を使います
• compat-custom-hooks-via-weakmap — 静的な getCompilationHooks と WeakMap を介してカスタムフックを公開します
• compat-feature-detection-not-version-check — API を直接検出し、webpack/package.json のバージョンを解析しません
• compat-export-shape-and-cjs-esm — プラグインクラスをデフォルトエクスポートし、CJS/ESM の相互運用性を提供します

使用方法

プラグインのコードを記述またはレビューする際は、AGENTS.md で該当するカテゴリを確認してから、個別のルールファイルを読んで詳細なパターンと根拠を確認してください。

• カテゴリの定義と影響度については、references/_sections.md から確認してください
• このスキルを拡張する場合は、ルールのテンプレートとして assets/templates/_template.md を参照してください
• 簡潔なナビゲーションインデックスについては、AGENTS.md を読んでください

参考ファイル

ファイル	説明
references/_sections.md	カテゴリの定義、影響度、説明
assets/templates/_template.md	新しいルールを作成するためのテンプレート
metadata.json	バージョン、分野、ソースの参照情報