webpack-plugin-recipes

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

本番環境を想定した webpack 5 プラグインのクックブックです。解決する問題ごとに 26 個のレシピを整理しています。各レシピでは、まず明確な問題を提示し（「これがないと何が困るのか」）、素朴な非プラグイン方式を示したうえで、説明、バリエーション、「使わないほうがよいケース」のガイダンスとともに、動作するプラグインを完全な形で紹介します（60～150 行）。

webpack-plugin-authoring とあわせてご利用ください。authoring では、あらゆるプラグインを正しく作成する「方法」を解説し、レシピでは、特定の課題に対して「どの」プラグインを作成すべきかを解説します。各レシピでは、適用する authoring のルールを相互参照しています。

適用するタイミング

次のような場合に、これらのレシピを参照してください。

• チームで「プラグインにすべきだと思う」ビルド時の問題（アーキテクチャルール、シークレットの漏えい防止、アセットの整理など）が繰り返し発生している
• webpack の出力を後続システム（SSR サーバー、CDN、監視システムなど）と連携させる必要がある
• 独自のプラグインを作成するか、既存のプラグインを採用するかを検討している。これらのレシピでは基本となるパターンを紹介しているため、適合性を判断できます
• 別のバンドラーから移行しており、フレームワーク形式の機能（ファイルシステムルーティング、仮想モジュールなど）を再現する必要がある
• 新しいエンジニアに webpack プラグインの作成方法を教えている。レシピでは現実的なエンドツーエンドの例を紹介しています

優先度別レシピカテゴリ

優先度	カテゴリ	影響度	接頭辞
1	ビルド時のガードレール	CRITICAL	guard-
2	ビルドメタデータとマニフェスト	HIGH	meta-
3	仮想モジュールとコード生成	HIGH	virtual-
4	コード変換	MEDIUM-HIGH	transform-
5	開発者エクスペリエンス	MEDIUM	dx-
6	アセットパイプライン	MEDIUM	assets-

クイックリファレンス

1. ビルド時のガードレール（CRITICAL）

• guard-bundle-budget — エントリーごとに設定した gzip 圧縮後の予算を初期 JS が超えた場合、ビルドを失敗させます
• guard-forbidden-imports — 禁止されたインポートがアーキテクチャの境界を越えた場合、ビルドを失敗させます
• guard-required-env-vars — 必須の環境変数が不足している場合、ビルドを失敗させます
• guard-no-secrets-bundled — シークレットらしき文字列がクライアントバンドルに漏れた場合、ビルドを失敗させます

2. ビルドメタデータとマニフェスト（HIGH）

• meta-inject-build-info — DefinePlugin を使って __COMMIT__／__BUILD_TIME__ をソースに注入し、build-info.json を出力します
• meta-asset-manifest — チャンクグループごとに、論理名 → ハッシュ付きファイル名を対応付けるマニフェストを出力します
• meta-license-notice — node_modules/ ではなくモジュールグラフをたどって LICENSES.txt を生成します
• meta-sri-manifest — CSP に準拠するため、アセットごとに SHA-384 SRI ハッシュを計算します

3. 仮想モジュールとコード生成（HIGH）

• virtual-module-from-memory — virtual:X インポートをメモリ内の文字列に解決します（Vite 形式）
• virtual-routes-from-filesystem — pages/ ディレクトリからルートマップを生成します（Next.js 形式）
• virtual-barrel-from-directory — ディレクトリから再エクスポートするバレルを自動生成します
• virtual-types-from-runtime — 実行時データ（設定ファイル、JSON スキーマなど）から .d.ts を出力します

4. コード変換（中〜高）

• transform-replace-library — 解決時に react を preact/compat に置き換えます（サブパスにも対応）
• transform-strip-debug-helpers — devAssert()／devLog() の呼び出しと開発環境専用のインポートを本番環境向けビルドから除去します
• transform-conditional-polyfill — 対象ブラウザーで実際に必要なポリフィルのみを挿入します（browserslist + core-js-compat）
• transform-banner-with-dynamic-content — 現在の年、バージョン、git コミットを含むチャンクごとのバナーを追加します
• transform-define-from-config — flags/staging.json 形式のファイルから DefinePlugin の置換を設定します

5. 開発者エクスペリエンス（中）

• dx-build-duration-report — ビルド時間を保存し、現在のビルドが中央値より30％以上遅い場合に警告します
• dx-notify-on-done — ビルド完了時にデスクトップ通知（ローカル）と Slack Webhook（CI）を送信します
• dx-diff-changed-chunks — リビルド間で実際に変更されたチャンクのみを表示します
• dx-open-browser-on-first-build — 初回ビルドが成功した後に開発サーバーの URL を開きます（成功前には開きません）

6. アセットパイプライン（中）

• assets-pre-compress-gzip-brotli — CDN 配信用に、事前圧縮された .gz／.br ファイルを生成します
• assets-optimize-images — imagemin を使って PNG／JPEG を最適化し、リビルド間でキャッシュを再利用します
• assets-route-by-type — 出力アセットを js/／css/／img/／fonts/ サブディレクトリに整理します
• assets-skip-empty-chunks — webpack／splitChunks／mini-css が不要に出力する0バイトのチャンクを削除します
• assets-add-cache-busting-query — 固定名アセット（manifest.json、sw.js）への参照に ?v=<hash> を追加します

使用方法

ユーザーが webpack の問題を説明した場合（またはプラグインを求めた場合）：

1. 問題のカテゴリを特定します（ガードレール？メタデータ？コード生成？変換？開発者エクスペリエンス？アセット？）
2. 該当するレシピファイルを開き、適切なレシピかどうかを確認するため、まず Problem セクションを読みます
3. 動作する出発点として Plugin セクションを使い、プロジェクトの具体的な要件に合わせて調整します
4. How it works を読み、各設計上の判断の背景にある理由を確認します（作成ルールへの相互参照があります）
5. 一般的な調整方法は Variations を確認し、適合性を確かめるために When NOT to use も確認します

プラグイン作成のパターンをより幅広く学ぶには、webpack-plugin-authoring スキルと組み合わせてください。そこにある44のルールでは、このスキルの各レシピで適用されている基礎的な API を学べます。

参照ファイル

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