esbuild-postcss

0.0.4 verified Mon Apr 27 auth: no javascript

A plugin for esbuild that seamlessly integrates PostCSS processing into the build pipeline. Version 0.0.4, with no recent updates. It works by matching file extensions (default .css) and running PostCSS transforms via a PostCSS instance configured in your project's postcss.config.js file. Unlike postcss-cli or webpack postcss-loader, this plugin is lightweight and leverages esbuild's speed. It requires esbuild and PostCSS 8+ as peer dependencies. Note: the package uses CommonJS require() style and does not expose an ESM module, which may cause issues in ESM-only environments.

Common errors

error Error: Cannot find module 'esbuild-postcss' ↓

cause The package is not installed or missing from dependencies.

fix

Run npm install esbuild-postcss --save-dev

error TypeError: postcss is not a function ↓

cause Using a named import `{ postcss }` when the package exports a default function.

fix

Use import postcss from 'esbuild-postcss' or const postcss = require('esbuild-postcss')

error Error: PostCSS plugin postcss-xxx requires PostCSS 8 ↓

cause PostCSS 8 is required but an older version is installed.

fix

Run npm install postcss@^8.0.0

Warnings

breaking The package is CJS-only. Using `import` syntax will cause a runtime error. ↓

fix Use `require('esbuild-postcss')` or add a bundler transform.

gotcha The plugin expects PostCSS to be configured via a postcss.config.js file or passed via options; it does not apply default transformations. ↓

fix Create a postcss.config.js with your plugins and options.

gotcha Only files with extensions in the `extensions` option (default ['.css']) are processed. If you have .pcss or .postcss files, they are ignored unless you add the extension. ↓

fix Pass a custom `extensions` array, e.g., `postcssPlugin({ extensions: ['.css', '.pcss'] })`.

gotcha The plugin does not handle source maps automatically; you must configure PostCSS source maps separately. ↓

fix Add source map support in your postcss.config.js.

Install

npm install esbuild-postcss

yarn add esbuild-postcss

pnpm add esbuild-postcss

Imports

default

wrong

import postcss from 'esbuild-postcss'

correct

const postcss = require('esbuild-postcss')

Package is CJS-only; ESM imports will fail.

postcss

wrong

import { postcss } from 'esbuild-postcss'

correct

import postcss from 'esbuild-postcss'

Default export is a function. Named export does not exist.

Options

const postcss = require('esbuild-postcss'); const result = postcss({ extensions: ['.css'] })

Options object passed to the default export function.

Quickstart

Shows how to use the esbuild-postcss plugin: create an esbuild build with a CSS entry point and the plugin.

const esbuild = require('esbuild');
const postcssPlugin = require('esbuild-postcss');

esbuild.build({
  entryPoints: ['src/styles.css'],
  bundle: true,
  outdir: 'dist',
  plugins: [postcssPlugin()],
}).catch(() => process.exit(1));