Clean Webpack Plugin

Common errors

• TypeError: CleanWebpackPlugin is not a constructor

  cause Attempting to instantiate the plugin without destructuring the named export, often seen with `new CleanWebpackPlugin()` after upgrading to v3+.
  fix Correct the import/require statement to use destructuring: `import { CleanWebpackPlugin } from 'clean-webpack-plugin';` or `const { CleanWebpackPlugin } = require('clean-webpack-plugin');`

• Error: Cannot find module 'clean-webpack-plugin'

  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.
  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).

• Files are not being cleaned or incorrect files are removed from my build directory.

  cause Incorrect configuration of `cleanOnceBeforeBuildPatterns` or misunderstanding its default behavior relative to `output.path` and watch mode.
  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.

Warnings

• breaking 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+).
  Fix: Upgrade Node.js to version 10 or higher and webpack to version 4 or higher, or use clean-webpack-plugin v3.x.
• breaking Version 3.0.0 changed the export from a default export to a named export `CleanWebpackPlugin`. Direct import without destructuring will fail.
  Fix: Update your import statements to `import { CleanWebpackPlugin } from 'clean-webpack-plugin';` for ESM or `const { CleanWebpackPlugin } = require('clean-webpack-plugin');` for CommonJS.
• breaking 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.
  Fix: Upgrade Node.js to version 8 or higher and webpack to version 3 or higher, or use clean-webpack-plugin v2.x.
• breaking 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.
  Fix: Review build logs to ensure cleanup occurs at the expected phase. No code changes are typically required unless specific timing dependencies exist.
• gotcha 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/**/*')`).
  Fix: When cleaning directories outside of webpack's output path, use `path.join(process.cwd(), 'your/path/**/*')` to provide an absolute path.

Install

• npm install clean-webpack-plugin npm
• yarn add clean-webpack-plugin yarn
• pnpm add clean-webpack-plugin pnpm

Imports

• CleanWebpackPlugin
  wrong:

  import CleanWebpackPlugin from 'clean-webpack-plugin';

  correct:

  import { CleanWebpackPlugin } from 'clean-webpack-plugin';

  Since v3.0.0, CleanWebpackPlugin is a named export. Default import is incorrect.
• CleanWebpackPlugin
  wrong:

  const CleanWebpackPlugin = require('clean-webpack-plugin');

  correct:

  const { CleanWebpackPlugin } = require('clean-webpack-plugin');

  Since v3.0.0, CleanWebpackPlugin is a named export and requires destructuring in CommonJS.

Quickstart

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.

import webpack from 'webpack';
import path from 'path';
import { CleanWebpackPlugin } from 'clean-webpack-plugin';

const webpackConfig: webpack.Configuration = {
    mode: 'development', // or 'production'
    entry: './src/index.ts',
    output: {
        path: path.resolve(__dirname, 'dist'),
        filename: 'bundle.js',
        // To demonstrate clean-webpack-plugin, disable Webpack 5's built-in clean
        clean: false,
    },
    resolve: {
        extensions: ['.ts', '.js'],
    },
    module: {
        rules: [
            {
                test: /\.ts$/,
                use: 'ts-loader',
                exclude: /node_modules/,
            },
        ],
    },
    plugins: [
        /**
         * The CleanWebpackPlugin will remove all files inside webpack's output.path directory
         * (e.g., `<PROJECT_DIR>/dist/`) once before the initial build. During rebuilds in watch mode,
         * it intelligently removes only the webpack assets that are no longer in use. This example
         * uses default options, which is often sufficient for most projects.
         */
        new CleanWebpackPlugin(),
    ],
};

// To use this configuration with the webpack CLI, save it as webpack.config.ts
// or webpack.config.js and run 'webpack' or 'webpack serve'.
// Alternatively, it can be consumed programmatically:
// const compiler = webpack(webpackConfig);
// compiler.run((err, stats) => {
//     if (err) { console.error(err); return; }
//     console.log(stats?.toString({ colors: true }));
// });

export default webpackConfig;