esbuild-postcss-plugin

0.0.7 verified Fri May 01 auth: no javascript maintenance

An ESBuild plugin that integrates PostCSS processing with support for CSS modules. Current version 0.0.7 is stable but infrequently updated. It allows you to apply PostCSS plugins (e.g., Autoprefixer) and CSS modules within the ESBuild bundler, with options for caching, file filtering, and module configuration. Unlike alternatives (e.g., esbuild-plugin-postcss2), this plugin explicitly supports CSS modules and provides a simple API. However, it has not been updated for over three years and may lack compatibility with newer PostCSS or ESBuild versions.

Common errors

error Error: esbuild-postcss-plugin: PostCSS options are invalid ↓

cause Invalid or missing `plugins` array in options.

fix

Ensure plugins is an array of PostCSS plugins: plugins: [require('autoprefixer')].

error TypeError: Cannot read property 'css' of undefined ↓

cause CSS module class names not exported because `postcss-modules` not properly configured.

fix

Ensure modulesFilter includes your .module.css files, e.g., modulesFilter: /\.module\.css$/.

error Error: Build failed with 1 error: error: No matching plugin for this file ↓

cause Plugin filter regex does not match the CSS file path.

fix

Set correct filter regex: filter: /\.css$/ or adjust to match your file extensions.

Warnings

gotcha Caching may cause incorrect results if PostCSS plugins depend on external files (e.g., Tailwind CSS). ↓

fix Set `disableCache: true` in plugin options to avoid stale output.

gotcha The `resolve`, `Loader`, and `root` options in `modulesOptions` are ignored. ↓

fix Do not use those options; use ESBuild's own resolve mechanisms instead.

gotcha The plugin may not work correctly with ESBuild versions newer than 0.12.x due to API changes. ↓

fix Check compatibility or use an alternative plugin like esbuild-plugin-postcss2.

gotcha Default import fails with TypeScript if `esModuleInterop` is not enabled. ↓

fix Enable `esModuleInterop` in tsconfig.json or use `import * as postCSSPlugin`.

Install

npm install esbuild-postcss-plugin

yarn add esbuild-postcss-plugin

pnpm add esbuild-postcss-plugin

Imports

default

wrong

const postCSSPlugin = require('esbuild-postcss-plugin')

correct

import postCSSPlugin from 'esbuild-postcss-plugin'

ESM default import works for TypeScript and modern JavaScript.

postCSSPlugin

wrong

import { postCSSPlugin } from 'esbuild-postcss-plugin'

correct

import postCSSPlugin from 'esbuild-postcss-plugin'

The package exports a function as default; named import is incorrect.

PostCSSPluginOptions
```
import type { PostCSSPluginOptions } from 'esbuild-postcss-plugin'
```
Type-only import for TypeScript users when defining options object.

Quickstart

Shows how to configure the plugin with PostCSS plugin (Autoprefixer) and custom CSS modules naming pattern.

import * as esbuild from 'esbuild'
import postCSSPlugin from 'esbuild-postcss-plugin'

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [postCSSPlugin({
    plugins: [require('autoprefixer')],
    modulesOptions: { generateScopedName: '[name]__[local]___[hash:base64:5]' }
  })]
})