esbuild-plugin-postcss

0.3.0 verified Fri May 01 auth: no javascript

An esbuild plugin for importing CSS/less/scss modules with TypeScript support. Version 0.3.0 is the latest stable release; the package has had infrequent updates. It enables CSS module extraction and automatic .d.ts declaration generation for less files. Differentiators include minimal configuration, built-in declaration file generation, and esbuild-native integration. Compared to alternatives like esbuild-sass-plugin, this plugin focuses on PostCSS ecosystem compatibility and TypeScript module resolution.

Common errors

error Error: Can't find PostCSS plugin ↓

cause PostCSS plugins not installed or missing in config

fix

npm install autoprefixer postcss-nested --save-dev and add to plugins array

error TypeError: PluginPostCSS is not a function ↓

cause Incorrect import style: trying named import instead of default

fix

Use import PluginPostCSS from 'esbuild-plugin-postcss' (default import)

error Error: require() of ES Module not supported ↓

cause Using CommonJS require() to load ESM-only package

fix

Switch to dynamic import() or use ESM for your project

error Cannot find module 'esbuild-plugin-postcss' ↓

cause Package not installed or incorrect import path

fix

npm install esbuild-plugin-postcss --save-dev and verify node_modules

Warnings

breaking v0.2.0 changed export from named 'PluginPostCSS' to default export only. ↓

fix Change import to default import: import PluginPostCSS from 'esbuild-plugin-postcss'

deprecated The 'declaration' option for .d.ts generation works only with Less files; other preprocessors not supported and may be deprecated in future. ↓

fix Use 'declaration: true' only for Less; for others, manually declare module types.

gotcha ESM-only package; require() in CommonJS module will throw ERR_REQUIRE_ESM. ↓

fix Use dynamic import() or set 'type': 'module' in package.json.

gotcha When using TypeScript, you must add a global module declaration for CSS/less files (e.g., '*.less' => Record<string, string>) to avoid type errors. ↓

fix Add a .d.ts file with declare module '*.less' { const content: Record<string, string>; export default content; }

Install

npm install esbuild-plugin-postcss

yarn add esbuild-plugin-postcss

pnpm add esbuild-plugin-postcss

Imports

default
wrong
```
const PluginPostCSS = require('esbuild-plugin-postcss')
```
correct
```
import PluginPostCSS from 'esbuild-plugin-postcss'
```
Package is ESM-only; CommonJS require will fail in Node ESM context. Use dynamic import or set type:module.

PluginPostCSS

wrong

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

correct

import PluginPostCSS from 'esbuild-plugin-postcss'

Only default export exists; false named import causes undefined.

PostCSSPluginOptions

wrong

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

correct

import type { PostCSSPluginOptions } from 'esbuild-plugin-postcss'

TypeScript type import only available since v0.2.0.

Quickstart

Shows esbuild build with PluginPostCSS, including autoprefixer and nested postcss plugins, and declaration generation.

import esbuild from 'esbuild';
import PluginPostCSS from 'esbuild-plugin-postcss';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outdir: 'dist',
  plugins: [
    PluginPostCSS({
      declaration: true, // generate .d.ts for CSS modules
      plugins: [
        require('autoprefixer'),
        require('postcss-nested'),
      ],
    }),
  ],
  loader: {
    '.tsx': 'tsx',
    '.ts': 'ts',
  },
});