esbuild-plugin-purgecss

0.0.6 verified Fri May 01 auth: no javascript

An esbuild plugin that integrates PurgeCSS to remove unused CSS from your bundled output. Currently at version 0.0.6 (stable, no recent updates). It allows configuration via PurgeCSS options and content paths. Key differentiator: lightweight, zero-config setup for esbuild users wanting to eliminate dead CSS during bundling. Alternatives like purgecss-webpack-plugin are more complex and Webpack-specific. Supports TypeScript types. Release cadence: low—last update over a year ago.

Common errors

error Error: Cannot find module 'purgecss' ↓

cause Missing peer dependency purgecss.

fix

Install purgecss: npm install purgecss

error TypeError: purgecssPlugin is not a function ↓

cause Using named import instead of default import.

fix

Use default import: import purgecssPlugin from 'esbuild-plugin-purgecss'

error No output files were generated ↓

cause Content paths don't match any HTML/JS files; no CSS to purge.

fix

Ensure content globs correctly resolve to files that reference CSS classes.

Warnings

gotcha Plugin only runs on CSS output, not on CSS files imported in JS. You must extract CSS (e.g., with esbuild's CSS loader) before purging. ↓

fix Ensure your esbuild build outputs CSS to a file; plugin will process it automatically.

deprecated Version 0.0.6 is the latest; no updates for over a year. May not support future esbuild versions. ↓

fix Consider switching to a more maintained alternative like purgecss-webpack-plugin if using webpack or check if the repo is active.

breaking Incompatible with esbuild's native CSS minification if you rely on content analysis—only first pass is done. ↓

fix Disable esbuild's CSS minification or chain plugins carefully.

gotcha Plugin options are passed directly to PurgeCSS; incorrect option names will silently fail (no error). ↓

fix Validate options against PurgeCSS documentation, e.g., use 'content' not 'paths'.

Install

npm install esbuild-plugin-purgecss

yarn add esbuild-plugin-purgecss

pnpm add esbuild-plugin-purgecss

Imports

default

wrong

const { purgecssPlugin } = require('esbuild-plugin-purgecss')

correct

import purgecssPlugin from 'esbuild-plugin-purgecss'

Default export only; named import will fail.

default (CommonJS)

wrong

const purgecssPlugin = require('esbuild-plugin-purgecss').default

correct

const purgecssPlugin = require('esbuild-plugin-purgecss')

CJS users: the plugin is the default export, no need for .default.

type definitions
```
import purgecssPlugin from 'esbuild-plugin-purgecss'
```
TypeScript types are included; use default import for type safety.

Quickstart

Basic usage: removes unused CSS by scanning HTML files for class references. Configurable content paths and safelist.

import purgecssPlugin from 'esbuild-plugin-purgecss';
import * as esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    purgecssPlugin({
      content: ['./src/**/*.html'],
      safelist: ['keep-me'],
    })
  ]
});