esbuild-plugin-purgecss-2

1.0.1 verified Fri May 01 auth: no javascript

An esbuild plugin for PurgeCSS that allows passing content (HTML/CSS) directly to the plugin configuration. Stable version 1.0.1 as of 2024. Based on the original esbuild-plugin-purgecss but with the added ability to specify content paths via plugin options, enabling tree-shaking of unused CSS during esbuild bundles. Supports glob patterns for content files. Ships TypeScript types, requires Node.js 10+, and works with esbuild v0.8+. A lightweight alternative to heavier PostCSS setups for CSS purging.

Common errors

error Error: Cannot find module 'esbuild-plugin-purgecss-2' ↓

cause Missing install or incorrect package name (note '-2' suffix).

fix

Run: npm install -D esbuild-plugin-purgecss-2

error TypeError: purgecssPlugin2 is not a function ↓

cause Using default import in CJS context without proper interop.

fix

In CJS, use: const purgecssPlugin2 = require('esbuild-plugin-purgecss-2'); or const purgecssPlugin2 = (await import('esbuild-plugin-purgecss-2')).default;

error Error: No content paths found. You must specify 'content' option. ↓

cause The content array is empty or null.

fix

Provide an array of file paths or glob patterns: content: glob.sync(['./*.html'])

Warnings

breaking The package uses ESM-only exports; using require() directly will fail unless you use dynamic import or set "type": "module". ↓

fix Use import() for CommonJS projects: const purgecssPlugin2 = (await import('esbuild-plugin-purgecss-2')).default;

deprecated The original esbuild-plugin-purgecss is unmaintained; this fork adds content pass-through but may not receive updates. ↓

fix Migrate to esbuild-plugin-purgecss-2 and adjust content option.

gotcha Glob patterns must match files that are accessible at build time; ensure path correctness to avoid empty content. ↓

fix Verify glob results: console.log(glob.sync(['./*.html'])) before passing to plugin.

gotcha The plugin only runs on CSS output from esbuild; if your CSS is imported via JS (e.g., import './style.css'), ensure esbuild handles CSS. ↓

fix Add --loader:.css=file to esbuild or configure loader accordingly.

Install

npm install esbuild-plugin-purgecss-2

yarn add esbuild-plugin-purgecss-2

pnpm add esbuild-plugin-purgecss-2

Imports

default
wrong
```
const purgecssPlugin2 = require('esbuild-plugin-purgecss-2')
```
correct
```
import purgecssPlugin2 from 'esbuild-plugin-purgecss-2'
```
ESM-only exports; requires "type": "module" in package.json for CJS projects. For CommonJS, use dynamic import().

purgecssPlugin2

wrong

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

correct

const purgecssPlugin2 = require('esbuild-plugin-purgecss-2')

CJS require returns the plugin function directly, not as named export.

PurgecssPluginOptions
```
import type { PurgecssPluginOptions } from 'esbuild-plugin-purgecss-2'
```
Type-only import for TypeScript users; available in v1.0.0+.

Quickstart

Demonstrates usage with esbuild build configuration, glob content paths, and plugin installation.

const glob = require('glob-all');
const purgecssPlugin2 = require('esbuild-plugin-purgecss-2');

require('esbuild').build({
  entryPoints: ['src/app.js'],
  bundle: true,
  outfile: 'dist/app.js',
  plugins: [
    purgecssPlugin2({
      content: glob.sync([
        './*.html',
        './views/**/*.html',
        './src/**/*.js',
      ]),
    }),
  ],
}).catch(() => process.exit(1));