{"id":21223,"library":"esbuild-css-modules-plugin","title":"esbuild-css-modules-plugin","description":"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.","status":"active","version":"3.1.5","language":"javascript","source_language":"en","source_url":"https://github.com/indooorsman/esbuild-css-modules-plugin","tags":["javascript","esbuild","plugin","esbuildplugin","esbuild plugin","css modules","fast","cssmodules","lightningcss","typescript"],"install":[{"cmd":"npm install esbuild-css-modules-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-css-modules-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-css-modules-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency required for plugin to function","package":"esbuild","optional":false}],"imports":[{"note":"ESM-only since v3; CommonJS require() will error. Use ESM imports.","wrong":"const CssModulesPlugin = require('esbuild-css-modules-plugin')","symbol":"CssModulesPlugin","correct":"import CssModulesPlugin from 'esbuild-css-modules-plugin'"},{"note":"The default export is CssModulesPlugin; named export cssModulesPlugin is also available.","wrong":"const cssModulesPlugin = require('esbuild-css-modules-plugin').cssModulesPlugin","symbol":"cssModulesPlugin","correct":"import { cssModulesPlugin } from 'esbuild-css-modules-plugin'"},{"note":"Options is a TypeScript type, not a runtime value. Use type import.","wrong":"import { Options } from 'esbuild-css-modules-plugin'","symbol":"Options","correct":"import type { Options } from 'esbuild-css-modules-plugin'"}],"quickstart":{"code":"import esbuild from 'esbuild';\nimport CssModulesPlugin from 'esbuild-css-modules-plugin';\n\nawait esbuild.build({\n  entryPoints: ['src/index.js'],\n  outfile: 'dist/bundle.js',\n  plugins: [\n    CssModulesPlugin({\n      force: true,\n      emitDeclarationFile: true,\n      localsConvention: 'camelCaseOnly',\n      namedExports: true,\n      inject: false\n    })\n  ],\n  bundle: true\n});","lang":"typescript","description":"Basic esbuild build with CSS Modules plugin, enabling named exports, type declarations, and camelCase class names."},"warnings":[{"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).","message":"Version 3.0 dropped CommonJS support; all imports must be ESM.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update Node.js to version 20 or later.","message":"Minimum Node version raised to 20 in v3; older versions not supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Replace `inject: true` with `force: true` in plugin options.","message":"The `inject` option is deprecated in v3; use `force` instead.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Ensure CSS class names only contain alphanumeric characters, $, and _, or set `localsConvention` to 'camelCaseOnly' to auto-convert.","message":"When `namedExports` is true, CSS class names must be valid JavaScript identifiers; otherwise, they are omitted or cause errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To process any CSS file, set `force: true` in plugin options.","message":"The plugin filters files by `.module.css` extension by default; CSS files without `.module.css` are ignored.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Switch to ESM imports or use dynamic import(): `const CssModulesPlugin = (await import('esbuild-css-modules-plugin')).default`.","cause":"Using CommonJS require() to import an ESM-only package (v3+).","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../esbuild-css-modules-plugin/index.js not supported."},{"fix":"Use default import: `import CssModulesPlugin from 'esbuild-css-modules-plugin'` and call it as a function: `CssModulesPlugin({...})`.","cause":"Using wrong import (e.g., default vs named) or incorrect plugin initialization.","error":"TypeError: CssModulesPlugin is not a function"},{"fix":"Run `npm install -D esbuild-css-modules-plugin` or check your package.json dependencies.","cause":"Package not installed or not in node_modules.","error":"Module not found: Error: Can't resolve 'esbuild-css-modules-plugin'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}