webpack-plugin-authoring

dot-skills Webpack 5 Plugins Best Practices

Comprehensive guide for writing correct, performant webpack 5 plugins. Contains 44 rules across 8 categories (8 hook + 7 asset + 5 cache + 5 life + 4 schema + 5 diag + 5 perf + 5 compat = 44), ordered by the authoring lifecycle: hook choice is the foundation, then asset manipulation, then caching/watch-mode correctness, then lifecycle hygiene, then user-facing concerns (schema validation, error reporting), then performance, then packaging.

Patterns are derived from webpack/webpack, the webpack-contrib plugin suite (mini-css-extract, terser, compression, copy, css-minimizer), and Next.js's webpack integration in vercel/next.js.

When to Apply

Reference these rules whenever:

• Writing a new plugin (defining apply(compiler), picking which hook to tap)
• Reviewing existing plugin code for correctness or performance
• Debugging "why isn't my plugin's output showing up" — usually a hook/stage mismatch
• Adding asset manipulation logic (processAssets, emitAsset, updateAsset)
• Fixing watch-mode staleness or persistent-cache poisoning
• Migrating a plugin from webpack 4 to webpack 5 (or supporting both)
• Publishing a plugin to npm (export shape, peerDependencies, schema)

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Hook Selection & Tap Patterns	CRITICAL	hook-
2	Asset Pipeline	CRITICAL	asset-
3	Caching & Watch Mode	HIGH	cache-
4	Plugin Lifecycle & State	HIGH	life-
5	Schema & Options Validation	MEDIUM-HIGH	schema-
6	Errors, Warnings & Logging	MEDIUM-HIGH	diag-
7	Performance & Parallelism	MEDIUM	perf-
8	Compatibility & Packaging	LOW-MEDIUM	compat-

Quick Reference

1. Hook Selection & Tap Patterns (CRITICAL)

• hook-tap-method-matches-hook-type — Match tap/tapAsync/tapPromise to the hook's Sync/Async type
• hook-thiscompilation-vs-compilation — Use thisCompilation to skip child compilations
• hook-process-assets-stage — Pick the right PROCESS_ASSETS_STAGE_* for your mutation
• hook-prefer-process-assets-over-emit — Mutate in processAssets, not emit
• hook-bail-hook-return-semantics — Return undefined from bail hooks unless intentionally stopping
• hook-tap-once-not-per-compilation — Register compiler hooks once in apply, not inside compilation hooks
• hook-name-matches-class-name — Use a stable tap name equal to the class name
• hook-normal-module-factory-stages — Tap normalModuleFactory at the right resolution stage (beforeResolve vs resolve vs afterResolve)

2. Asset Pipeline (CRITICAL)

• asset-emit-asset-not-direct-assignment — Use emitAsset/updateAsset, never compilation.assets[name] = ...
• asset-source-from-compiler-webpack — Import source classes from compiler.webpack.sources
• asset-preserve-source-maps — Use SourceMapSource/ReplaceSource to keep maps attached
• asset-set-info-metadata — Set info.immutable, info.contenthash, info.related when emitting
• asset-content-hash-via-output-options — Hash via compilation.outputOptions.hashFunction, not hardcoded md5
• asset-delete-then-emit-loses-info — Use renameAsset to move; deleteAsset+emitAsset severs chunk references
• asset-buffer-not-source-for-binary — Use buffer() not source() for binary assets

3. Caching & Watch Mode (HIGH)

• cache-add-file-dependencies — Add read files to compilation.fileDependencies
• cache-context-dependencies-for-directories — Use contextDependencies for directory scans
• cache-missing-dependencies-for-optional-files — Add probed-but-absent paths to missingDependencies
• cache-build-dependencies-for-persistent-cache — Declare buildDependencies for persistent cache invalidation
• cache-use-input-file-system — Read via compiler.inputFileSystem, not Node fs

4. Plugin Lifecycle & State (HIGH)

• life-constructor-stores-options-only — Constructor only validates and stores; side effects belong in apply()
• life-no-mutable-state-across-builds — Scope mutable state per-compilation via local const or WeakMap
• life-multi-compiler-isolation — One plugin instance per compiler; or use WeakMap<Compiler, T>
• life-cleanup-in-shutdown-hook — Clean up workers, watchers, fds in compiler.hooks.shutdown
• life-defensively-copy-user-options — Never mutate the user's options object

5. Schema & Options Validation (MEDIUM-HIGH)

• schema-validate-with-schema-utils — Validate via schema-utils.validate() and a JSON Schema
• schema-name-and-base-data-path — Set name and baseDataPath for navigable error messages
• schema-additional-properties-false — Set additionalProperties: false on every object to catch typos
• schema-tap-into-validate-hook — Defer cross-field validation to compiler.hooks.validate (5.106+)

6. Errors, Warnings & Logging (MEDIUM-HIGH)

• diag-push-webpack-error-not-throw — Push WebpackError to compilation.errors, don't throw
• diag-use-compilation-get-logger — Log via compilation.getLogger('Plugin'), not console
• diag-attach-loc-to-errors — Attach loc and module to errors for IDE click-through
• diag-warnings-vs-errors-exit-codes — Errors fail the build; warnings don't — choose intentionally
• diag-progress-reporting — Report progress via context.reportProgress (opt in with context: true)

7. Performance & Parallelism (MEDIUM)

• perf-jest-worker-for-cpu-bound-work — Offload CPU-bound work to a jest-worker pool
• perf-cache-results-with-compilation-cache — Cache expensive work via compilation.getCache(name).providePromise
• perf-traverse-chunks-not-modules — Iterate compilation.chunks not compilation.modules when possible
• perf-avoid-source-toString-in-hot-paths — Avoid source().toString() for assets you only inspect
• perf-respect-experimental-options — Honor experiments.cacheUnaffected / incremental

8. Compatibility & Packaging (LOW-MEDIUM)

• compat-webpack-as-peer-dependency — Declare webpack as peerDependencies, not dependencies
• compat-use-compiler-webpack-namespace — Use compiler.webpack.* instead of require('webpack')
• compat-custom-hooks-via-weakmap — Expose custom hooks via static getCompilationHooks + WeakMap
• compat-feature-detection-not-version-check — Detect APIs directly; don't parse webpack/package.json version
• compat-export-shape-and-cjs-esm — Export the plugin class as default; provide CJS/ESM interop

How to Use

When writing or reviewing plugin code, scan AGENTS.md for the relevant category, then read the individual rule file for the full pattern and rationale.

• Start at references/_sections.md for category definitions and impact levels
• See assets/templates/_template.md for the rule template if you want to extend this skill
• Read AGENTS.md for a compact navigation index

Reference Files

File	Description
references/_sections.md	Category definitions, impact levels, descriptions
assets/templates/_template.md	Template for authoring new rules
metadata.json	Version, discipline, source references