esbuild-plugin-css-modules

0.3.0 verified Fri May 01 auth: no javascript

A plugin for esbuild that adds CSS Modules support, enabling local scoping of CSS class names. Current stable version is 0.3.0. The plugin allows developers to import CSS files as JavaScript modules, receiving a mapping of local class names to globally unique names. It supports custom naming patterns via replacement tokens like [local], [hash], and [ext], and can target specific file extensions (default .module.css). Written in TypeScript with bundled types. Release cadence is slow; last update was in 2021. Key differentiator: lightweight integration with esbuild, unlike webpack-based alternatives.

Common errors

error Error: Build failed with 1 error: error: Could not resolve "./test.module.css" ↓

cause Plugin not loaded correctly or CSS file not matching extension pattern.

fix

Install and register the plugin in esbuild plugins array, and ensure filename ends with .module.css (or adjust extension option).

error TypeError: cssModulesPlugin is not a function ↓

cause Incorrect import style: using named import instead of default.

fix

Use import cssModulesPlugin from 'esbuild-plugin-css-modules' or const cssModulesPlugin = require('esbuild-plugin-css-modules')

error Cannot find module 'esbuild' ↓

cause esbuild is a peer dependency and not installed.

fix

Run npm install -D esbuild to install it alongside the plugin.

Warnings

breaking ESM default import is a function; CJS require yields function directly. ↓

fix Use default import pattern: import cssModulesPlugin from 'esbuild-plugin-css-modules'

gotcha Options object is optional; passing invalid options does not error. ↓

fix Ensure options keys match the Options interface exactly.

gotcha File extension defaults to .module.css; other extensions are ignored. ↓

fix Set extension option to process CSS files with a different extension, e.g., '.css'

deprecated The plugin has not been updated since 2021 and may not support latest esbuild features. ↓

fix Consider alternative plugins like 'esbuild-plugin-css' or 'esbuild-sass-plugin' for active maintenance.

Install

npm install esbuild-plugin-css-modules

yarn add esbuild-plugin-css-modules

pnpm add esbuild-plugin-css-modules

Imports

cssModulesPlugin (default import)

wrong

const cssModulesPlugin = require('esbuild-plugin-css-modules'); const { cssModulesPlugin } = require('esbuild-plugin-css-modules')

correct

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

ESM and CJS are both supported.

Options type

wrong

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

correct

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

Options is only exported as a type, not a value. Use type-only import.

Calling the plugin

wrong

new cssModulesPlugin({ localIdentName: '[local]--[hash:8]' })

correct

cssModulesPlugin({ localIdentName: '[local]--[hash:8]' })

The export is a function, not a class. Do not use 'new'.

Quickstart

Bundles a JavaScript entry point, applying CSS Modules to .module.css files with a custom naming pattern.

const esbuild = require('esbuild');
const cssModulesPlugin = require('esbuild-plugin-css-modules');
esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'bundle.js',
  plugins: [
    cssModulesPlugin({
      localIdentName: '[local]--[hash:8:md5:hex]',
    }),
  ],
}).catch((e) => console.error(e.message));