Vite Plugin Clean Build

1.4.1 · active · verified Tue Apr 21

vite-plugin-clean-build is a Vite plugin designed to remove or clean specified files and directories after the build process completes. It is currently at version 1.4.1 and maintains an active release cadence, with frequent minor updates addressing bug fixes, performance optimizations, and compatibility with new Vite versions (e.g., supporting Vite 5.0 and 6.0 in recent releases). Key differentiators include its straightforward configuration for specifying an `outputDir` and glob patterns for removal, alongside an optional verbose logging mode to track deleted files. This plugin is particularly useful for tasks such as cleaning up temporary assets, specific cache directories, or unwanted build artifacts that Vite's default build process might leave behind, ensuring a leaner and more controlled final build output.

Common errors

```
TypeError: (0 , vite_plugin_clean_build_1.default) is not a function
```
cause The imported `CleanBuild` function was not invoked with `()` when added to the `plugins` array.

fix Ensure the plugin is called: `plugins: [CleanBuild()]` instead of `plugins: [CleanBuild]`.
```
[vite-plugin-clean-build] The output directory 'dist' does not exist.
```
cause The `outputDir` configured in the plugin does not match Vite's actual `build.outDir`, or the build failed before creating the directory.

fix Ensure `outputDir` in the plugin options precisely matches `build.outDir` in your Vite configuration. Verify that your Vite build completes successfully.
```
Could not resolve "vite-plugin-clean-build" from "vite.config.ts"
```
cause The `vite-plugin-clean-build` package is not installed or incorrectly installed in your project's `node_modules`.

fix Run `npm install vite-plugin-clean-build -D`, `yarn add vite-plugin-clean-build -D`, or `pnpm add vite-plugin-clean-build -D` to install the package as a dev dependency.
```
Plugin "vite-plugin-clean-build" requires Vite version ">=3.0.0", but you are running "2.x.x".
```
cause Your installed `vite` version does not meet the peer dependency requirement of `vite-plugin-clean-build`.

fix Upgrade your Vite installation to a compatible version (e.g., `npm update vite`) or, if necessary, downgrade `vite-plugin-clean-build` to a version compatible with your current Vite installation.

Warnings

breaking The plugin's minor versions often align with new Vite major versions. For instance, v1.2.1 supports Vite 5.0, and v1.3.0 supports Vite 6.0. Using an incompatible plugin version with your Vite installation can lead to build failures or unexpected behavior.
Fix: Always ensure your `vite-plugin-clean-build` version is compatible with your installed `vite` version, referring to the plugin's release notes for specific compatibility matrix.
gotcha By default, `vite-plugin-clean-build` targets the `dist` directory. If your Vite project uses a different `build.outDir`, you must explicitly configure the `outputDir` option to match it, otherwise, the plugin will clean the wrong directory or do nothing.
Fix: Set `outputDir` in the plugin configuration to match your `vite.config.ts`'s `build.outDir` (e.g., `outputDir: 'my-custom-output'`).
gotcha The `patterns` option uses `glob` syntax. Ensure you understand how glob patterns work, especially for negation (`!`) and directory matching, to avoid accidentally deleting critical files or failing to delete intended ones. Patterns are relative to `outputDir`.
Fix: Test your glob patterns carefully, perhaps using a dedicated glob testing tool, and start with `verbose: true` in the plugin options to confirm what files are being targeted for deletion.
gotcha The cleaning process occurs after Vite's build step completes. If subsequent build processes or scripts rely on intermediate files in the output directory, those files might be removed before they can be used.
Fix: Plan your build pipeline carefully, ensuring that `vite-plugin-clean-build` runs at an appropriate stage, typically as the very last step involving the build output, or adjust your dependent scripts.

Install

npm install vite-plugin-clean-build npm
yarn add vite-plugin-clean-build yarn
pnpm add vite-plugin-clean-build pnpm

Imports

CleanBuild
wrong:
```
const CleanBuild = require('vite-plugin-clean-build');
```
correct:
```
import CleanBuild from 'vite-plugin-clean-build';
```
Vite configuration files are typically ESM, so `import` syntax is standard. The plugin exports a default function.
CleanBuild (invocation)
wrong:
```
plugins: [CleanBuild]
```
correct:
```
plugins: [CleanBuild()]
```
The imported `CleanBuild` is a function that must be called (invoked) to return the plugin instance for Vite's `plugins` array.
Options (type)
wrong:
```
import { Options } from 'vite-plugin-clean-build';
```
correct:
```
import type { Options } from 'vite-plugin-clean-build';
```
For TypeScript, explicitly importing `Options` as a type ensures it's only used for type-checking and no runtime import is generated.

Quickstart

This quickstart demonstrates how to integrate `vite-plugin-clean-build` into a Vite configuration, specifying custom output directories and glob patterns for cleaning, along with verbose logging, and showing how to import the configuration type for type-safety.

import { defineConfig } from 'vite';
import CleanBuild from 'vite-plugin-clean-build';
import type { Options } from 'vite-plugin-clean-build'; // Demonstrate type import

const cleanBuildOptions: Options = {
  outputDir: 'dist', // Default, but explicit for clarity
  patterns: [
    'images/**',       // Clean all images within 'dist/images'
    '!images/logo.png',// Except the logo file in 'dist/images'
    'temp/*'           // Also clean temporary files in 'dist/temp'
  ],
  verbose: true,       // Log deleted files to console
};

export default defineConfig({
  plugins: [
    CleanBuild(cleanBuildOptions),
  ],
  build: {
    outDir: cleanBuildOptions.outputDir, // Ensure Vite builds to the same directory
  },
});

view raw JSON →