Registry / devops / esbuild-clean-plugin

esbuild-clean-plugin

JSON →
library2.0.0jsnpmunverified

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.

npm install esbuild-clean-plugin
INSTALL
IMPORT
SIG · ESBUILD-CLEAN-PLUG
E
esbuild-clean-plugin
devopsjavascriptv2.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

cleanPlugin
import { cleanPlugin } from 'esbuild-clean-plugin';
const cleanPlugin = require('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.

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);
Debug
Known issues
breakingesbuild-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.
affects: <2.0.0
breakingesbuild-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`.
affects: <2.0.0
gotchaThe `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.
affects: >=2.0.0
Errors
Common errors & fixes
ERR_REQUIRE_ESM
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.
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.
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.
Upgrade
Version history
2.0.0latest on npm
Audit
Dependencies
esbuildrequiredRequired as a peer dependency for plugin functionality.
Agent activity
25 hits · last 30 days
node
24
OpenAI (training)
1
Resources
esbuild-clean-plugin — npm install esbuild-clean-plugin · libregistry