esbuild-plugin-react18-css

0.0.4 verified Fri May 01 auth: no javascript

An ESBuild plugin (v0.0.4) for handling CSS/SCSS modules with autoprefixer, treeshakable CSS, and full TypeScript support. It automatically converts CSS/SCSS modules to BEM-like scoped names without hashes by default for easier library CSS overrides. Unlike similar plugins, it is designed specifically for React 18 server components and supports treeshakable imports (e.g., import from 'esbuild-plugin-react18-css/client/component'). Release cadence is low (4 releases in early 2024); the project is maintained but still in early development (0.x). Requires esbuild as a peer dependency.

Common errors

error Cannot find module 'esbuild-plugin-react18-css' ↓

cause Package not installed or ESM/CJS mismatch.

fix

npm install esbuild-plugin-react18-css --save-dev

error [esbuild] Error: [plugin: css] Cannot read properties of undefined (reading 'includes') ↓

cause Passing undefined or invalid options to cssPlugin.

fix

Ensure cssPlugin() is called with an object or no arguments: cssPlugin({}) or cssPlugin().

error TypeError: require() of ES Module /node_modules/esbuild-plugin-react18-css/index.mjs not supported ↓

cause Using require() in CJS project.

fix

Switch to ESM (type: 'module' in package.json) or use dynamic import: await import('esbuild-plugin-react18-css').

error Module '"esbuild-plugin-react18-css"' has no exported member 'CSSPluginOptions' ↓

cause Trying to import type as value instead of using type-only import.

fix

Use import type { CSSPluginOptions } from 'esbuild-plugin-react18-css'.

Warnings

gotcha Default generateScopedName does not include hash, which may cause classname collisions in large projects. ↓

fix Set generateScopedName to include a hash, e.g., '[name]__[local]___[hash:base64:5]'.

deprecated The skipAutoPrefixer option is deprecated in favor of explicit postcss configuration. ↓

fix Use a separate postcss plugin with autoprefixer for more control.

breaking Package is ESM-only since v0.0.1; require() will fail. ↓

fix Use import syntax or set up your project for ESM.

gotcha Plugin does not import types correctly if using TypeScript without type import. ↓

fix Use import type { CSSPluginOptions } from 'esbuild-plugin-react18-css'.

gotcha CSS modules are always processed; no option to skip CSS files from node_modules. ↓

fix Filter out node_modules in the plugin's setup function manually.

Install

npm install esbuild-plugin-react18-css

yarn add esbuild-plugin-react18-css

pnpm add esbuild-plugin-react18-css

Imports

cssPlugin

wrong

const cssPlugin = require('esbuild-plugin-react18-css')

correct

import cssPlugin from 'esbuild-plugin-react18-css'

ESM-only; no default export in CommonJS. The package is ESM-only as of v0.0.1.

CSSPluginOptions

wrong

import { CSSPluginOptions } from 'esbuild-plugin-react18-css'

correct

import type { CSSPluginOptions } from 'esbuild-plugin-react18-css'

Use type import for TypeScript types; CSSPluginOptions is a type interface, not a runtime value.

cssPlugin (default)
wrong
```
import { cssPlugin } from 'esbuild-plugin-react18-css'
```
correct
```
import cssPlugin from 'esbuild-plugin-react18-css'
```
The package exports a default export, not a named export. Named import will result in 'undefined'.

Quickstart

Shows basic integration of esbuild-plugin-react18-css with esbuild, including plugin options for scoped class names and autoprefixer.

import cssPlugin from 'esbuild-plugin-react18-css';
import esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/index.tsx'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [cssPlugin({
    generateScopedName: '[name]__[local]___[hash:base64:5]',
    skipAutoPrefixer: false,
    globalPrefix: 'my-app'
  })],
});