{"id":15603,"library":"esbuild-clean-plugin","title":"esbuild Clean Plugin","description":"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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","esbuild","plugin","clean","typescript"],"install":[{"cmd":"npm install esbuild-clean-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-clean-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-clean-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for plugin functionality.","package":"esbuild","optional":false}],"imports":[{"note":"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.","wrong":"const cleanPlugin = require('esbuild-clean-plugin');","symbol":"cleanPlugin","correct":"import { cleanPlugin } from 'esbuild-clean-plugin';"},{"note":"For TypeScript users, import the `CleanPluginOptions` type to ensure type safety when configuring the plugin options.","symbol":"CleanPluginOptions","correct":"import type { CleanPluginOptions } from 'esbuild-clean-plugin';"}],"quickstart":{"code":"import * as esbuild from 'esbuild';\nimport { cleanPlugin } from 'esbuild-clean-plugin';\nimport path from 'path';\nimport { fileURLToPath } from 'url';\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\n\nasync function build() {\n  // Ensure a 'dist' directory exists or will be created by esbuild\n  // For demonstration, let's create a dummy entry file.\n  // In a real scenario, this would be your actual source code.\n  const entryPoint = path.resolve(__dirname, 'index.js');\n  await esbuild.build({\n    entryPoints: [entryPoint],\n    bundle: true,\n    outfile: path.resolve(__dirname, 'dist', 'bundle.js')\n  });\n\n  const context = await esbuild.context({\n    bundle: true,\n    entryPoints: [path.resolve(__dirname, 'index.js')],\n    metafile: true, // Required for the plugin to work\n    outdir: path.resolve(__dirname, 'dist'), // Required for the plugin to work\n    plugins: [cleanPlugin({\n      // Optional: Clean all files initially before the build starts\n      initialCleanPatterns: ['**/*', '!package.json'],\n      verbose: true // See what gets deleted\n    })],\n  });\n\n  // In a typical setup, you might watch or build once\n  // For this quickstart, we'll just perform an initial build with the plugin.\n  await context.rebuild();\n  console.log('Build complete and output directory cleaned.');\n\n  // To stop the watch context if it were started:\n  // await context.dispose();\n}\n\n// Create a dummy index.js for the quickstart to run\nimport { promises as fs } from 'fs';\nawait fs.writeFile(path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'index.js'), 'console.log(\"Hello from esbuild!\");');\n\nbuild().catch(console.error);\n","lang":"typescript","description":"This quickstart demonstrates setting up `esbuild-clean-plugin` within an esbuild context, showcasing how to configure it for initial directory cleaning and verbose output."},"warnings":[{"fix":"Upgrade your Node.js environment to version 22.11.0 or newer. Consider using `nvm` or similar version managers.","message":"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.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Ensure your project's `esbuild` dependency is updated to version `^0.18.20` or newer. Run `npm install esbuild@latest`.","message":"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.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Always include `metafile: true` and `outdir: 'your/output/directory'` in your `esbuild.build` or `esbuild.context` configuration when using this plugin.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Use ES Module `import` syntax: `import { cleanPlugin } from 'esbuild-clean-plugin';`","cause":"Attempting to import `esbuild-clean-plugin` using CommonJS `require()` syntax in an ES Module environment.","error":"ERR_REQUIRE_ESM"},{"fix":"Add `metafile: true` to your `esbuild` configuration object.","cause":"The esbuild configuration is missing the `metafile: true` option, which is necessary for the plugin to track build outputs.","error":"Error: The 'metafile' option must be set to true for esbuild-clean-plugin to work."},{"fix":"Add `outdir: 'your/build/directory'` to your `esbuild` configuration object.","cause":"The esbuild configuration is missing the `outdir` option, preventing the plugin from identifying the target directory for cleaning.","error":"Error: The 'outdir' option must be set for esbuild-clean-plugin to work."}],"ecosystem":"npm"}