> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webpack.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# CleanPlugin

> Clean the output directory before each build

# CleanPlugin

The `CleanPlugin` removes/cleans the output directory (typically `dist`) before each build, ensuring that only files generated by the current build are present.

<Note>
  In webpack 5, this functionality is built into the core through the `output.clean` option. The plugin is still available for advanced use cases.
</Note>

## Basic Usage

**Simple approach (webpack 5+):**

```javascript theme={null}
module.exports = {
  output: {
    path: path.resolve(__dirname, 'dist'),
    clean: true // Enable automatic cleaning
  }
};
```

**Using the plugin directly:**

```javascript theme={null}
const webpack = require('webpack');

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

## Configuration Options

<ParamField path="clean" type="boolean | object" default="false">
  Enable cleaning of the output directory.

  When set to `true`, removes all files in the output directory before emit.
</ParamField>

<ParamField path="clean.dry" type="boolean" default="false">
  Log what would be removed instead of actually removing it (dry run).
</ParamField>

<ParamField path="clean.keep" type="string | RegExp | function">
  Keep specific files/directories that match the pattern.

  ```javascript theme={null}
  {
    output: {
      clean: {
        keep: /\.git/ // Keep .git directory
      }
    }
  }
  ```
</ParamField>

## Advanced Usage

### Keep Specific Files

Keep certain files while cleaning others:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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

<Warning>
  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.
</Warning>

## Use Cases

### Remove Old Build Artifacts

Automatically clean up old bundles when filenames include hashes:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
// 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):**

```javascript theme={null}
const { CleanWebpackPlugin } = require('clean-webpack-plugin');

module.exports = {
  plugins: [
    new CleanWebpackPlugin()
  ]
};
```

**After (webpack 5):**

```javascript theme={null}
module.exports = {
  output: {
    clean: true
  }
};
```

## Related

* [Output Configuration](/configuration/output) - Output directory and file options
* [Production Guide](/guides/production) - Production build best practices
* [Caching Guide](/guides/caching) - Cache busting with content hashes