esbuild Clean Plugin

2.0.0 · active · verified Tue Apr 21

esbuild-clean-plugin is a utility designed to integrate with esbuild's build process to automatically clean the designated output directory. It's currently stable at version 2.0.0, indicating a mature and maintained state. While a specific release cadence isn't explicitly stated, plugins often follow a release cycle aligned with their host bundler or address specific feature/bug updates as needed. Its primary differentiator lies in its deep integration as an esbuild plugin, leveraging esbuild's internal context to precisely identify and clean generated files. It offers crucial options like `initialCleanPatterns` to clear the directory before a new build, `dry` run mode for testing, and `verbose` output to track deleted files, providing fine-grained control over the build folder lifecycle directly within the esbuild configuration. This makes it a robust solution for ensuring a clean build environment without external scripts.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to import `esbuild-clean-plugin` using CommonJS `require()` syntax in an ES Module environment.

fix Use ES Module `import` syntax: `import { cleanPlugin } from 'esbuild-clean-plugin';`
```
Error: The 'metafile' option must be set to true for esbuild-clean-plugin to work.
```
cause The esbuild configuration is missing the `metafile: true` option, which is necessary for the plugin to track build outputs.

fix Add `metafile: true` to your `esbuild` configuration object.
```
Error: The 'outdir' option must be set for esbuild-clean-plugin to work.
```
cause The esbuild configuration is missing the `outdir` option, preventing the plugin from identifying the target directory for cleaning.

fix Add `outdir: 'your/build/directory'` to your `esbuild` configuration object.

Warnings

breaking esbuild-clean-plugin v2.0.0 requires Node.js version 22.11.0 or later. Older Node.js versions are not supported and will likely result in runtime errors.
Fix: Upgrade your Node.js environment to version 22.11.0 or newer. Consider using `nvm` or similar version managers.
breaking esbuild-clean-plugin v2.0.0 requires esbuild version 0.18.20 or later as a peer dependency. Using an older version of esbuild may lead to compatibility issues or the plugin failing to function correctly.
Fix: Ensure your project's `esbuild` dependency is updated to version `^0.18.20` or newer. Run `npm install esbuild@latest`.
gotcha The `esbuild-clean-plugin` will not have any effect unless both the `metafile: true` and `outdir` options are explicitly set in your esbuild configuration. Without these, the plugin cannot determine which files to clean.
Fix: Always include `metafile: true` and `outdir: 'your/output/directory'` in your `esbuild.build` or `esbuild.context` configuration when using this plugin.

Install

npm install esbuild-clean-plugin npm
yarn add esbuild-clean-plugin yarn
pnpm add esbuild-clean-plugin pnpm

Imports

cleanPlugin
wrong:
```
const cleanPlugin = require('esbuild-clean-plugin');
```
correct:
```
import { cleanPlugin } from 'esbuild-clean-plugin';
```
The library primarily uses ES Modules. Direct `require()` syntax will lead to an `ERR_REQUIRE_ESM` error in Node.js environments unless transpiled or configured appropriately.
CleanPluginOptions
```
import type { CleanPluginOptions } from 'esbuild-clean-plugin';
```
For TypeScript users, import the `CleanPluginOptions` type to ensure type safety when configuring the plugin options.

Quickstart

This quickstart demonstrates setting up `esbuild-clean-plugin` within an esbuild context, showcasing how to configure it for initial directory cleaning and verbose output.

import * as esbuild from 'esbuild';
import { cleanPlugin } from 'esbuild-clean-plugin';
import path from 'path';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

async function build() {
  // Ensure a 'dist' directory exists or will be created by esbuild
  // For demonstration, let's create a dummy entry file.
  // In a real scenario, this would be your actual source code.
  const entryPoint = path.resolve(__dirname, 'index.js');
  await esbuild.build({
    entryPoints: [entryPoint],
    bundle: true,
    outfile: path.resolve(__dirname, 'dist', 'bundle.js')
  });

  const context = await esbuild.context({
    bundle: true,
    entryPoints: [path.resolve(__dirname, 'index.js')],
    metafile: true, // Required for the plugin to work
    outdir: path.resolve(__dirname, 'dist'), // Required for the plugin to work
    plugins: [cleanPlugin({
      // Optional: Clean all files initially before the build starts
      initialCleanPatterns: ['**/*', '!package.json'],
      verbose: true // See what gets deleted
    })],
  });

  // In a typical setup, you might watch or build once
  // For this quickstart, we'll just perform an initial build with the plugin.
  await context.rebuild();
  console.log('Build complete and output directory cleaned.');

  // To stop the watch context if it were started:
  // await context.dispose();
}

// Create a dummy index.js for the quickstart to run
import { promises as fs } from 'fs';
await fs.writeFile(path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'index.js'), 'console.log("Hello from esbuild!");');

build().catch(console.error);

view raw JSON →