esbuild-plugin-class-modules

2.1.9 verified Fri May 01 auth: no javascript

An esbuild plugin that compiles CSS/SCSS/Sass stylesheets using Sass, PostCSS, and CSS Modules. Version 2.1.9 ships TypeScript types and supports global and local scoped outputs. It filters files by extension (.css, .module.css, .scss, .module.scss, .sass, etc.) and allows customization of Sass options, PostCSS plugins, and CSS Modules settings. Differentiates by combining Sass compilation with PostCSS processing and CSS Modules in one plugin, with support for global scoping via file naming or import style (named vs default import).

Common errors

error Error: Cannot find module 'sass' ↓

cause sass is not installed; it's a peer dependency.

fix

Run npm install -D sass

error TypeError: classModules is not a function ↓

cause Importing the default export instead of named export.

fix

Use const { classModules } = require('esbuild-plugin-class-modules');

error Error: No matching plugin for file extension .scss ↓

cause The plugin's default filter regex does not include .scss? Ensure file extension matches.

fix

Set custom filter: { filter: /\.scss$/i }

error Error: PostCSS plugin not found ↓

cause PostCSS is not installed or not configured in options.postcss.

fix

Install postcss and add plugins to options.postcss array.

Warnings

breaking From v2, the plugin no longer includes sass or postcss as dependencies; they must be installed separately. ↓

fix Ensure sass and postcss are in your devDependencies.

gotcha If you use both this plugin and another CSS plugin, classModules must be listed after the other CSS plugin in the plugins array. ↓

fix Reorder plugins array: other CSS plugins first, then classModules.

gotcha Global scope via default import: import './styles.css' treats classes as global, while named import import styles from './styles.css' enables local scoping. ↓

fix Use named imports for CSS Modules local scoping; default imports for global styles.

deprecated The old import path 'esbuild-plugin-class-modules/dist' is no longer available. ↓

fix Import directly from 'esbuild-plugin-class-modules'.

Install

npm install esbuild-plugin-class-modules

yarn add esbuild-plugin-class-modules

pnpm add esbuild-plugin-class-modules

Imports

classModules

wrong

const classModules = require('esbuild-plugin-class-modules');

correct

import { classModules } from 'esbuild-plugin-class-modules'

The package supports both ESM and CJS; named export only.

ClassModulesOptions

wrong

import { ClassModulesOptions } from 'esbuild-plugin-class-modules'

correct

import type { ClassModulesOptions } from 'esbuild-plugin-class-modules'

Type-only import for TypeScript users.

CssCompilerOptions
```
import { CssCompilerOptions } from 'esbuild-plugin-class-modules'
```
Type available for TypeScript users; not a runtime value.

Quickstart

Shows minimal setup to bundle JS with CSS/SCSS compiled via Sass, PostCSS, and CSS Modules.

const esbuild = require('esbuild');
const { classModules } = require('esbuild-plugin-class-modules');

esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  bundle: true,
  plugins: [classModules()]
}).then(() => {
  console.log('Build complete');
}).catch(() => process.exit(1));