esbuild-css-modules-plugin

3.1.5 verified Mon Apr 27 auth: no javascript

An esbuild plugin that bundles CSS Modules into JavaScript/TypeScript files using Lightning CSS for fast transformation. Version 3.1.5 requires Node >= 20 and esbuild as a peer dependency. It supports both bundled and unbundled builds, offering features like type declaration generation, camelCase class renaming, and named exports. Key differentiators: built on Lightning CSS for speed, works with `bundle: false` to produce standalone .css.js files, and provides full TypeScript type definitions. Release cadence is active with frequent updates.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module .../esbuild-css-modules-plugin/index.js not supported. ↓

cause Using CommonJS require() to import an ESM-only package (v3+).

fix

Switch to ESM imports or use dynamic import(): const CssModulesPlugin = (await import('esbuild-css-modules-plugin')).default.

error TypeError: CssModulesPlugin is not a function ↓

cause Using wrong import (e.g., default vs named) or incorrect plugin initialization.

fix

Use default import: import CssModulesPlugin from 'esbuild-css-modules-plugin' and call it as a function: CssModulesPlugin({...}).

error Module not found: Error: Can't resolve 'esbuild-css-modules-plugin' ↓

cause Package not installed or not in node_modules.

fix

Run npm install -D esbuild-css-modules-plugin or check your package.json dependencies.

Warnings

breaking Version 3.0 dropped CommonJS support; all imports must be ESM. ↓

fix Update imports to use ES module syntax: `import CssModulesPlugin from 'esbuild-css-modules-plugin'` and ensure your project uses ESM (e.g., `"type": "module"` in package.json).

breaking Minimum Node version raised to 20 in v3; older versions not supported. ↓

fix Update Node.js to version 20 or later.

deprecated The `inject` option is deprecated in v3; use `force` instead. ↓

fix Replace `inject: true` with `force: true` in plugin options.

gotcha When `namedExports` is true, CSS class names must be valid JavaScript identifiers; otherwise, they are omitted or cause errors. ↓

fix Ensure CSS class names only contain alphanumeric characters, $, and _, or set `localsConvention` to 'camelCaseOnly' to auto-convert.

gotcha The plugin filters files by `.module.css` extension by default; CSS files without `.module.css` are ignored. ↓

fix To process any CSS file, set `force: true` in plugin options.

Install

npm install esbuild-css-modules-plugin

yarn add esbuild-css-modules-plugin

pnpm add esbuild-css-modules-plugin

Imports

CssModulesPlugin

wrong

const CssModulesPlugin = require('esbuild-css-modules-plugin')

correct

import CssModulesPlugin from 'esbuild-css-modules-plugin'

ESM-only since v3; CommonJS require() will error. Use ESM imports.

cssModulesPlugin

wrong

const cssModulesPlugin = require('esbuild-css-modules-plugin').cssModulesPlugin

correct

import { cssModulesPlugin } from 'esbuild-css-modules-plugin'

The default export is CssModulesPlugin; named export cssModulesPlugin is also available.

Options

wrong

import { Options } from 'esbuild-css-modules-plugin'

correct

import type { Options } from 'esbuild-css-modules-plugin'

Options is a TypeScript type, not a runtime value. Use type import.

Quickstart

Basic esbuild build with CSS Modules plugin, enabling named exports, type declarations, and camelCase class names.

import esbuild from 'esbuild';
import CssModulesPlugin from 'esbuild-css-modules-plugin';

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/bundle.js',
  plugins: [
    CssModulesPlugin({
      force: true,
      emitDeclarationFile: true,
      localsConvention: 'camelCaseOnly',
      namedExports: true,
      inject: false
    })
  ],
  bundle: true
});