{"id":25327,"library":"esbuild-plugin-css-modules","title":"esbuild-plugin-css-modules","description":"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.","status":"active","version":"0.3.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","esbuild","plugin","css","css-modules","typescript"],"install":[{"cmd":"npm install esbuild-plugin-css-modules","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-css-modules","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-css-modules","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency required to provide the bundler runtime","package":"esbuild","optional":false}],"imports":[{"note":"ESM and CJS are both supported.","wrong":"const cssModulesPlugin = require('esbuild-plugin-css-modules'); const { cssModulesPlugin } = require('esbuild-plugin-css-modules')","symbol":"cssModulesPlugin (default import)","correct":"import cssModulesPlugin from 'esbuild-plugin-css-modules'"},{"note":"Options is only exported as a type, not a value. Use type-only import.","wrong":"import { Options } from 'esbuild-plugin-css-modules'","symbol":"Options type","correct":"import type { Options } from 'esbuild-plugin-css-modules'"},{"note":"The export is a function, not a class. Do not use 'new'.","wrong":"new cssModulesPlugin({ localIdentName: '[local]--[hash:8]' })","symbol":"Calling the plugin","correct":"cssModulesPlugin({ localIdentName: '[local]--[hash:8]' })"}],"quickstart":{"code":"const esbuild = require('esbuild');\nconst cssModulesPlugin = require('esbuild-plugin-css-modules');\nesbuild.build({\n  entryPoints: ['src/index.js'],\n  bundle: true,\n  outfile: 'bundle.js',\n  plugins: [\n    cssModulesPlugin({\n      localIdentName: '[local]--[hash:8:md5:hex]',\n    }),\n  ],\n}).catch((e) => console.error(e.message));","lang":"javascript","description":"Bundles a JavaScript entry point, applying CSS Modules to .module.css files with a custom naming pattern."},"warnings":[{"fix":"Use default import pattern: import cssModulesPlugin from 'esbuild-plugin-css-modules'","message":"ESM default import is a function; CJS require yields function directly.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Ensure options keys match the Options interface exactly.","message":"Options object is optional; passing invalid options does not error.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Set extension option to process CSS files with a different extension, e.g., '.css'","message":"File extension defaults to .module.css; other extensions are ignored.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Consider alternative plugins like 'esbuild-plugin-css' or 'esbuild-sass-plugin' for active maintenance.","message":"The plugin has not been updated since 2021 and may not support latest esbuild features.","severity":"deprecated","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install and register the plugin in esbuild plugins array, and ensure filename ends with .module.css (or adjust extension option).","cause":"Plugin not loaded correctly or CSS file not matching extension pattern.","error":"Error: Build failed with 1 error: error: Could not resolve \"./test.module.css\""},{"fix":"Use `import cssModulesPlugin from 'esbuild-plugin-css-modules'` or `const cssModulesPlugin = require('esbuild-plugin-css-modules')`","cause":"Incorrect import style: using named import instead of default.","error":"TypeError: cssModulesPlugin is not a function"},{"fix":"Run `npm install -D esbuild` to install it alongside the plugin.","cause":"esbuild is a peer dependency and not installed.","error":"Cannot find module 'esbuild'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}