Agent Skills: dot-skills Webpack 5 Plugins Best Practices

dot-skills Webpack 5 Plugins Best Practices

Cookbook of 26 production-shaped webpack 5 plugins, organized by the problem they solve. Each recipe starts with a clearly defined problem statement ("here's what hurts without this"), shows the naive non-plugin approach, then provides a complete working plugin (60-150 lines) with explanation, variations, and "when NOT to use" guidance.

Companion to webpack-plugin-authoring — authoring teaches how to write any plugin correctly; recipes teach which plugin to write for a specific pain point. Recipes cross-reference the authoring rules they apply.

When to Apply

Reference these recipes whenever:

• A team has a recurring build-time problem that "feels like it should be a plugin" (architecture rules, secret leak prevention, asset organization)
• You need to integrate webpack output with downstream systems (SSR servers, CDNs, monitoring)
• You're considering whether to write your own plugin OR adopt an existing one — these recipes show the underlying pattern so you can judge fit
• Migrating from another bundler and need to recreate framework-style features (filesystem routing, virtual modules)
• Onboarding new engineers to webpack plugin authoring — recipes give realistic, end-to-end examples

Recipe Categories by Priority

| Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Build-time Guardrails | CRITICAL | guard- | | 2 | Build Metadata & Manifests | HIGH | meta- | | 3 | Virtual Modules & Codegen | HIGH | virtual- | | 4 | Code Transformation | MEDIUM-HIGH | transform- | | 5 | Developer Experience | MEDIUM | dx- | | 6 | Asset Pipeline | MEDIUM | assets- |

Quick Reference

1. Build-time Guardrails (CRITICAL)

• guard-bundle-budget — Fail builds when initial JS exceeds a per-entry gzipped budget
• guard-forbidden-imports — Fail builds when forbidden imports cross architectural boundaries
• guard-required-env-vars — Fail builds when required environment variables are missing
• guard-no-secrets-bundled — Fail builds when secret-shaped strings leak into client bundles

2. Build Metadata & Manifests (HIGH)

• meta-inject-build-info — Inject __COMMIT__/__BUILD_TIME__ into source via DefinePlugin + emit build-info.json
• meta-asset-manifest — Emit chunk-grouped manifest mapping logical names → hashed filenames
• meta-license-notice — Generate LICENSES.txt by walking the module graph (not node_modules/)
• meta-sri-manifest — Compute SHA-384 SRI hashes per asset for CSP compliance

3. Virtual Modules & Codegen (HIGH)

• virtual-module-from-memory — Resolve virtual:X imports to in-memory strings (Vite-style)
• virtual-routes-from-filesystem — Generate route map from pages/ directory (Next.js-style)
• virtual-barrel-from-directory — Auto-generate barrel re-exports from a directory
• virtual-types-from-runtime — Emit .d.ts from runtime data (config files, JSON schemas)

4. Code Transformation (MEDIUM-HIGH)

• transform-replace-library — Replace react with preact/compat at resolve (with subpath handling)
• transform-strip-debug-helpers — Strip devAssert()/devLog() calls + dev-only imports from production
• transform-conditional-polyfill — Inject only the polyfills target browsers actually need (browserslist + core-js-compat)
• transform-banner-with-dynamic-content — Per-chunk banners with current year, version, git commit
• transform-define-from-config — Drive DefinePlugin substitutions from a flags/staging.json-style file

5. Developer Experience (MEDIUM)

• dx-build-duration-report — Persist build durations, warn when current build is >30% slower than median
• dx-notify-on-done — Desktop notification (local) + Slack webhook (CI) on build complete
• dx-diff-changed-chunks — Print only the chunks that actually changed between rebuilds
• dx-open-browser-on-first-build — Open the dev-server URL AFTER first successful build (not before)

6. Asset Pipeline (MEDIUM)

• assets-pre-compress-gzip-brotli — Emit .gz/.br siblings for CDN-served pre-compression
• assets-optimize-images — Optimize PNG/JPEG with imagemin + cache reuse across rebuilds
• assets-route-by-type — Organize emitted assets into js//css//img//fonts/ subdirectories
• assets-skip-empty-chunks — Delete the 0-byte chunks webpack/splitChunks/mini-css emit unnecessarily
• assets-add-cache-busting-query — Append ?v=<hash> to references of fixed-name assets (manifest.json, sw.js)

How to Use

When the user describes a webpack problem (or asks for a plugin):

1. Identify the problem category (guardrail? metadata? codegen? transformation? dx? asset?)
2. Open the matching recipe file — read the Problem section first to confirm it's the right recipe
3. Use the Plugin section as a working starting point — adapt to the project's specifics
4. Read How it works for the WHY behind each design choice (cross-references the authoring rules)
5. Check Variations for common adaptations and When NOT to use to confirm the fit

For learning plugin authoring patterns more broadly, pair with the webpack-plugin-authoring skill — its 44 rules teach the underlying APIs every recipe in this skill applies.

Reference Files

| File | Description | |------|-------------| | references/_sections.md | Category definitions and impact levels | | assets/templates/_template.md | Template for authoring new recipes | | metadata.json | Version and source references |