esbuild-style-plugin

1.6.3 verified Mon Apr 27 auth: no javascript

An esbuild plugin for processing CSS, SASS, LESS, and STYLUS files. Version 1.6.3. It handles CSS modules via PostCSS, supports reading postcss.config.js, and extracts CSS by default. Preprocessors are not bundled; you install only what you need (sass, less, stylus). It ships TypeScript definitions and supports both ESM and CJS builds. Key differentiators: SSR-friendly (extract: false keeps CSS modules mapping), dynamic preprocessor imports, and built-in PostCSS integration without requiring additional configuration plugins.

Common errors

error Cannot find module 'sass' ↓

cause Missing preprocessor installation.

fix

Install the preprocessor: npm i -D sass (or less, stylus)

error stylePlugin is not a function ↓

cause Using named import instead of default import.

fix

Use 'import stylePlugin from 'esbuild-style-plugin'' instead of 'import { stylePlugin }'

error TypeError: Cannot read properties of undefined (reading 'module') ↓

cause postcss not installed when using CSS modules or PostCSS options.

fix

Install postcss: npm i -D postcss

Warnings

gotcha Preprocessors are not bundled; must install sass, less, or stylus separately or get runtime error. ↓

fix Run npm i -D sass (or less/stylus) for the preprocessor you need.

gotcha CSSNano should not be used as a PostCSS plugin; it will cause issues and duplicates esbuild minification. ↓

fix Remove cssnano from postcss.plugins; let esbuild handle minification.

deprecated postcssConfigFile: true uses root folder — may be ambiguous in monorepos. ↓

fix Use an absolute path string instead of boolean true for clarity.

gotcha When extract: false, CSS is not emitted; only CSS modules class mappings are available for SSR. ↓

fix Set extract: true to output CSS files, or keep false for SSR and handle CSS injection server-side.

Install

npm install esbuild-style-plugin

yarn add esbuild-style-plugin

pnpm add esbuild-style-plugin

Imports

stylePlugin
wrong
```
const stylePlugin = require('esbuild-style-plugin')
```
correct
```
import stylePlugin from 'esbuild-style-plugin'
```
Default export is ESM-friendly; require() works but preferred import for consistency.
stylePlugin
wrong
```
import { stylePlugin } from 'esbuild-style-plugin'
```
correct
```
import stylePlugin from 'esbuild-style-plugin'
```
The package exports a default function, not a named export. Named import will give undefined.
StylePluginOptions
```
import type { StylePluginOptions } from 'esbuild-style-plugin'
```
TypeScript types are available for the options object, exported as a named type.

Quickstart

Basic esbuild build using esbuild-style-plugin with all options explicitly set, showing ESM import and TypeScript usage.

import esbuild from 'esbuild';
import stylePlugin from 'esbuild-style-plugin';

await esbuild.build({
  entryPoints: ['./src/index.js'],
  bundle: true,
  outdir: './dist',
  plugins: [
    stylePlugin({
      extract: true,
      cssModulesMatch: '\.module\.css$',
      renderOptions: {
        sassOptions: {},
        lessOptions: {},
        stylusOptions: {}
      },
      postcss: {
        plugins: []
      },
      postcssConfigFile: false
    })
  ]
});