clean-webpack-plugin

clean-webpack-plugin is a small, focused webpack plugin that keeps your output directory tidy. By default it deletes everything inside webpack’s output.path once before the first build, and then automatically removes any asset from a previous compilation that is no longer produced by the current one — so switching branches, renaming chunks, or changing content hashes never leaves orphaned files behind in dist/.

Under the hood it hooks into webpack’s emit and done compiler lifecycle events and delegates the actual filesystem work to del, giving it full glob pattern support (including negative ! patterns to protect specific files or directories). Options like dry (simulate without deleting), verbose (log every removal), cleanStaleWebpackAssets, and protectWebpackAssets let teams tune exactly how aggressive the cleanup is, while dangerouslyAllowCleanPatternsOutsideProject gives an explicit, clearly-named escape hatch for the rare case of cleaning paths outside the project root.

It supports webpack 4 and 5, ships full TypeScript type definitions, and requires no configuration to get useful default behavior — for most projects, adding new CleanWebpackPlugin() to the plugins array is the entire integration.

What You Get

• Zero-config default behavior — new CleanWebpackPlugin() cleans the entire output directory once before the first build
• Automatic removal of stale assets after every rebuild, comparing the current compilation’s asset list against the previous one
• Glob-based pattern control via cleanOnceBeforeBuildPatterns and cleanAfterEveryBuildPatterns, including negative !exclude patterns
• A dry mode that logs what would be deleted without touching the filesystem, useful for verifying patterns before enabling real deletion
• Full TypeScript type definitions shipped with the package

Common Use Cases

• Preventing old content-hashed bundles (e.g. main.[contenthash].js) from piling up in dist/ across rebuilds
• Cleaning a build directory once at the start of a fresh webpack --mode production run without a separate rm -rf dist step in package.json scripts
• Removing files generated by other plugins or loaders that aren’t tracked as webpack assets, via cleanAfterEveryBuildPatterns
• Verifying which files a cleanup configuration would remove before enabling it, using dry: true and verbose: true together

Under The Hood

Architecture The entire plugin is a single class (CleanWebpackPlugin in src/clean-webpack-plugin.ts) that taps into two webpack compiler hooks: emit (used once, guarded by an initialClean flag, to run the before-build cleanup) and done (used on every compilation to diff the current asset list against the previous one and remove anything stale). State is minimal — just the running list of currentAssets and the resolved outputPath — and all constructor-time validation (rejecting non-plain-object options, rejecting the removed allowExternal option) happens up front so misconfiguration fails fast with a clear error rather than silently doing nothing.

Tech Stack Written in TypeScript and compiled with Babel (@babel/preset-typescript) rather than tsc directly, with tsc --project tsconfig.types.json used only to emit declaration files. The only runtime dependency is del (glob-based file deletion), and webpack itself is a peer dependency supporting >=4.0.0 <6.0.0. Tooling includes ESLint with a shared config, Prettier, Husky-driven pre-commit/pre-push hooks running lint-staged, and a test.all step that runs the suite against multiple installed webpack versions via a custom dev-utils/test-supported-webpack-versions.js harness.

Code Quality Test coverage is extensive relative to the implementation — the single source file is under 350 lines while its Jest test suite exceeds 1,300 lines, exercising real webpack compiler runs (via temp-sandbox for isolated filesystem fixtures) rather than mocking webpack’s internals. Errors are handled explicitly: filesystem failures are caught in removeFiles, checked against a known error-message pattern, and re-thrown with a clearer message when the failure is the common “outside project root” case. CI runs on both Linux (CircleCI) and Windows (AppVeyor) across multiple Node versions, with type-checking and linting as separate required steps.

What Makes It Unique The plugin’s main design decision is being deliberately narrow: rather than trying to be a general file-management plugin, it does exactly one thing — diffing webpack’s own asset output between builds — and exposes the underlying del glob syntax directly instead of inventing a new pattern language. The dangerouslyAllowCleanPatternsOutsideProject naming is a notable safety-by-naming choice: the option that expands blast radius outside the project directory is impossible to enable by accident because its name states the risk.