Skip to main content

​
CleanPlugin

The CleanPlugin removes/cleans the output directory (typically dist) before each build, ensuring that only files generated by the current build are present.
In webpack 5, this functionality is built into the core through the output.clean option. The plugin is still available for advanced use cases.

​
Basic Usage

Simple approach (webpack 5+): 
module.exports = {
  output: {
    path: path.resolve(__dirname, 'dist'),
    clean: true // Enable automatic cleaning
  }
};
Using the plugin directly: 
const webpack = require('webpack');

module.exports = {
  plugins: [
    new webpack.CleanPlugin()
  ]
};

​
Configuration Options

​
clean
boolean | object
default:"false"
Enable cleaning of the output directory.When set to true, removes all files in the output directory before emit.
​
clean.dry
boolean
default:"false"
Log what would be removed instead of actually removing it (dry run).
​
clean.keep
string | RegExp | function
Keep specific files/directories that match the pattern.
{
  output: {
    clean: {
      keep: /\.git/ // Keep .git directory
    }
  }
}

​
Advanced Usage

​
Keep Specific Files

Keep certain files while cleaning others: 
module.exports = {
  output: {
    path: path.resolve(__dirname, 'dist'),
    clean: {
      keep: (asset) => {
        // Keep .gitkeep and LICENSE files
        return asset.includes('.gitkeep') || asset === 'LICENSE';
      }
    }
  }
};

​
Keep Pattern

Use glob patterns to specify files to keep: 
module.exports = {
  output: {
    path: path.resolve(__dirname, 'dist'),
    clean: {
      keep: /\.git/, // Keep anything with .git in the path
    }
  }
};

​
Dry Run

Test what would be deleted without actually deleting: 
module.exports = {
  output: {
    path: path.resolve(__dirname, 'dist'),
    clean: {
      dry: true, // Only log, don't delete
      keep: 'important.txt'
    }
  }
};

​
How It Works

The CleanPlugin:
  1. Runs before webpack emits files to the output directory
  2. Reads the current contents of the output directory
  3. Compares with the list of assets webpack will emit
  4. Removes files/directories not in the current build
  5. Respects the keep option to preserve specified files
Be careful when using clean: true with complex build setups or multiple webpack configurations targeting the same output directory. Files from other builds may be removed.

​
Use Cases

​
Remove Old Build Artifacts

Automatically clean up old bundles when filenames include hashes: 
module.exports = {
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js',
    clean: true // Remove old hashed files
  }
};

​
Preserve Static Assets

Keep manually added files in the output directory: 
module.exports = {
  output: {
    path: path.resolve(__dirname, 'dist'),
    clean: {
      keep: (asset) => {
        // Keep manually added assets
        return asset.startsWith('static/');
      }
    }
  }
};

​
Multi-Compiler Setup

When using multiple webpack configs with the same output: 
// webpack.config.js
module.exports = [
  {
    name: 'client',
    output: {
      path: path.resolve(__dirname, 'dist'),
      clean: {
        keep: 'server.js' // Keep server bundle when building client
      }
    }
  },
  {
    name: 'server',
    output: {
      path: path.resolve(__dirname, 'dist'),
      clean: {
        keep: /^client/, // Keep client files when building server
      }
    }
  }
];

​
Migration from webpack 4

In webpack 4, you typically used clean-webpack-plugin. In webpack 5, use the built-in option: Before (webpack 4): 
const { CleanWebpackPlugin } = require('clean-webpack-plugin');

module.exports = {
  plugins: [
    new CleanWebpackPlugin()
  ]
};
After (webpack 5): 
module.exports = {
  output: {
    clean: true
  }
};