esbuild-plugin-lightningcss-modules

0.1.2 verified Fri May 01 auth: no javascript

A minimal CSS Modules plugin for esbuild using Lightning CSS (Rust-based) for transformations. Version 0.1.2, with monthly releases. Supports the `composes` feature with dependencies (`composes: mixin from './mixin.module.css'`), which other esbuild CSS modules plugins often fail to handle correctly due to reliance on postcss-modules. Tested with ~100 CSS modules in production. Requires esbuild ~0.16.0 or ~0.17.0 as a peer dependency. Simpler than alternatives like `esbuild-css-modules-plugin` but with fewer features.

Common errors

error Error: Build failed with 1 error: error: No loader is configured for ".module.css" files: src/styles.module.css ↓

cause The plugin is not installed or loaded in esbuild plugins array.

fix

Ensure cssModules() is added to plugins array in esbuild.build call.

error TypeError: cssModules is not a function ↓

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

fix

Use named import: import { cssModules } from 'esbuild-plugin-lightningcss-modules'

Warnings

breaking CSS files without .module.css extension are not treated as CSS modules by default. Use includeFilter to override. ↓

fix Add includeFilter: /\.css$/ to the plugin options if your CSS modules lack the .module.css extension.

deprecated The plugin only supports esbuild versions ~0.16.0 or ~0.17.0. Newer esbuild versions may not work. ↓

fix Pin esbuild to 0.16.x or 0.17.x, or consider an alternative plugin that supports newer esbuild.

gotcha The plugin does not support CSS modules without explicit .module.css suffix if other CSS files exist; use excludeFilter to prevent global CSS from being processed as modules. ↓

fix Set excludeFilter: /node_modules\/some-lib\/styles\.css/ to exclude global CSS.

Install

npm install esbuild-plugin-lightningcss-modules

yarn add esbuild-plugin-lightningcss-modules

pnpm add esbuild-plugin-lightningcss-modules

Imports

cssModules
wrong
```
const cssModules = require('esbuild-plugin-lightningcss-modules')
```
correct
```
import { cssModules } from 'esbuild-plugin-lightningcss-modules'
```
Named export; default export not supported. CommonJS require works for older Node.js versions but prefer ES import.

Quickstart

Shows how to configure esbuild with the plugin, enabling CSS Modules and nesting support.

import { cssModules } from 'esbuild-plugin-lightningcss-modules';
import * as esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    cssModules({
      targets: { chrome: 80 },
      drafts: { nesting: true },
    }),
  ],
});