Registry / web-framework / esbuild-plugin-css-modules

esbuild-plugin-css-modules

library0.3.0jsnpmunverified

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.

web-framework

npm install esbuild-plugin-css-modules

package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-CSS

esbuild-plugin-css-modules

web-frameworkjavascriptv0.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

cssModulesPlugin (default import)

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

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

ESM and CJS are both supported.

Options type

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

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

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

Calling the plugin

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

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

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

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));

Debug

Known issues

breakingESM default import is a function; CJS require yields function directly.

fix

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

affects: >=0.1.0

gotchaOptions object is optional; passing invalid options does not error.

fix

Ensure options keys match the Options interface exactly.

affects: >=0.1.0

gotchaFile extension defaults to .module.css; other extensions are ignored.

fix

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

affects: >=0.1.0

deprecatedThe 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.

affects: >=0.1.0

Errors

Common errors & fixes

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

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).

TypeError: cssModulesPlugin is not a function

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')`

Cannot find module 'esbuild'

esbuild is a peer dependency and not installed.

fix

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

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

esbuildrequiredpeer dependency required to provide the bundler runtime

Agent activity

4 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/esbuild-plugin-css-modules ↗