{"id":15301,"library":"clean-webpack-plugin","title":"Clean Webpack Plugin","description":"clean-webpack-plugin is a utility designed to clean or remove build folders before or after webpack compilations. Its current stable version is 4.0.0, which supports Node.js 14+ and webpack 5+. The plugin typically sees major version updates to align with breaking changes in Node.js and webpack, ensuring compatibility with the latest ecosystem features. Key differentiators include its simplicity, with no configuration needed for standard usage (cleaning webpack's output.path directory), and its intelligent handling of webpack's watch mode where it only removes assets generated by webpack that are no longer in use. It leverages the 'del' package for robust globbing support, allowing for flexible pattern matching to define what should be cleaned. It is a fundamental tool for maintaining clean build directories in webpack projects.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/johnagan/clean-webpack-plugin","tags":["javascript","webpack","plugin","clean","node","typescript"],"install":[{"cmd":"npm install clean-webpack-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add clean-webpack-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add clean-webpack-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for webpack integration.","package":"webpack","optional":false}],"imports":[{"note":"Since v3.0.0, CleanWebpackPlugin is a named export. Default import is incorrect.","wrong":"import CleanWebpackPlugin from 'clean-webpack-plugin';","symbol":"CleanWebpackPlugin","correct":"import { CleanWebpackPlugin } from 'clean-webpack-plugin';"},{"note":"Since v3.0.0, CleanWebpackPlugin is a named export and requires destructuring in CommonJS.","wrong":"const CleanWebpackPlugin = require('clean-webpack-plugin');","symbol":"CleanWebpackPlugin","correct":"const { CleanWebpackPlugin } = require('clean-webpack-plugin');"}],"quickstart":{"code":"import webpack from 'webpack';\nimport path from 'path';\nimport { CleanWebpackPlugin } from 'clean-webpack-plugin';\n\nconst webpackConfig: webpack.Configuration = {\n    mode: 'development', // or 'production'\n    entry: './src/index.ts',\n    output: {\n        path: path.resolve(__dirname, 'dist'),\n        filename: 'bundle.js',\n        // To demonstrate clean-webpack-plugin, disable Webpack 5's built-in clean\n        clean: false,\n    },\n    resolve: {\n        extensions: ['.ts', '.js'],\n    },\n    module: {\n        rules: [\n            {\n                test: /\\.ts$/,\n                use: 'ts-loader',\n                exclude: /node_modules/,\n            },\n        ],\n    },\n    plugins: [\n        /**\n         * The CleanWebpackPlugin will remove all files inside webpack's output.path directory\n         * (e.g., `<PROJECT_DIR>/dist/`) once before the initial build. During rebuilds in watch mode,\n         * it intelligently removes only the webpack assets that are no longer in use. This example\n         * uses default options, which is often sufficient for most projects.\n         */\n        new CleanWebpackPlugin(),\n    ],\n};\n\n// To use this configuration with the webpack CLI, save it as webpack.config.ts\n// or webpack.config.js and run 'webpack' or 'webpack serve'.\n// Alternatively, it can be consumed programmatically:\n// const compiler = webpack(webpackConfig);\n// compiler.run((err, stats) => {\n//     if (err) { console.error(err); return; }\n//     console.log(stats?.toString({ colors: true }));\n// });\n\nexport default webpackConfig;","lang":"typescript","description":"This configuration demonstrates the basic setup for `clean-webpack-plugin` in a webpack project. It initializes the plugin with its default settings, which automatically cleans the output directory before the initial build and manages stale assets during subsequent rebuilds, ensuring a clean build folder for a TypeScript project."},"warnings":[{"fix":"Upgrade Node.js to version 10 or higher and webpack to version 4 or higher, or use clean-webpack-plugin v3.x.","message":"Version 4.0.0 dropped support for Node.js 8 and webpack 3. Ensure your environment meets the new requirements (Node.js 10+, webpack 4+).","severity":"breaking","affected_versions":"4.0.0"},{"fix":"Update your import statements to `import { CleanWebpackPlugin } from 'clean-webpack-plugin';` for ESM or `const { CleanWebpackPlugin } = require('clean-webpack-plugin');` for CommonJS.","message":"Version 3.0.0 changed the export from a default export to a named export `CleanWebpackPlugin`. Direct import without destructuring will fail.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade Node.js to version 8 or higher and webpack to version 3 or higher, or use clean-webpack-plugin v2.x.","message":"Version 3.0.0 dropped support for Node.js 6 and webpack 2. Projects using these older versions must remain on clean-webpack-plugin v2.x.","severity":"breaking","affected_versions":"3.0.0"},{"fix":"Review build logs to ensure cleanup occurs at the expected phase. No code changes are typically required unless specific timing dependencies exist.","message":"In v3.0.0, the `cleanOnceBeforeBuildPatterns` option now uses webpack's `emit` hook instead of `compile`. This might slightly alter the timing of the cleanup process.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"When cleaning directories outside of webpack's output path, use `path.join(process.cwd(), 'your/path/**/*')` to provide an absolute path.","message":"The `cleanOnceBeforeBuildPatterns` option specifies patterns relative to webpack's `output.path` directory. For paths outside `output.path`, full absolute paths must be provided (e.g., `path.join(process.cwd(), 'build/**/*')`).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Correct the import/require statement to use destructuring: `import { CleanWebpackPlugin } from 'clean-webpack-plugin';` or `const { CleanWebpackPlugin } = require('clean-webpack-plugin');`","cause":"Attempting to instantiate the plugin without destructuring the named export, often seen with `new CleanWebpackPlugin()` after upgrading to v3+.","error":"TypeError: CleanWebpackPlugin is not a constructor"},{"fix":"Ensure the package is installed (`npm install --save-dev clean-webpack-plugin`) and that your Node.js and webpack versions meet the plugin's requirements (Node.js 10+ and webpack 4+ for v4.0.0).","cause":"Typically indicates that the package is not installed or there's a problem with module resolution in the environment, possibly due to unsupported Node.js or webpack versions.","error":"Error: Cannot find module 'clean-webpack-plugin'"},{"fix":"First, test with `dry: true` and `verbose: true` in the plugin options to log actions without actual file deletion. Review `cleanOnceBeforeBuildPatterns` to ensure glob patterns are correct and paths are absolute if outside `output.path`. Remember that by default, it cleans `output.path` before build and stale webpack assets during rebuilds.","cause":"Incorrect configuration of `cleanOnceBeforeBuildPatterns` or misunderstanding its default behavior relative to `output.path` and watch mode.","error":"Files are not being cleaned or incorrect files are removed from my build directory."}],"ecosystem":"npm"}