esbuild-plugin-react18-css

0.0.4 verified Fri May 01 auth: no javascript

An ESBuild plugin for handling CSS and SCSS modules with autoprefixer, BEM-like scoped class names, and full tree-shaking support. Version 0.0.4 is the latest, with active development and frequent releases. Key differentiators: integrates seamlessly with ESBuild and tsup, provides full TypeScript support, offers customizable scoped class name generation, and enables fully tree-shakable CSS for React 18 libraries. It supports CSS modules, SCSS modules, and PostCSS autoprefixer out of the box.

Common errors

error Error: Must use import to load ES Module: esbuild-plugin-react18-css ↓

cause Using require() on an ESM-only package.

fix

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

error Error: Cannot find module 'autoprefixer' ↓

cause autoprefixer not installed but skipAutoPrefixer is false (default).

fix

Run npm install autoprefixer or set skipAutoPrefixer: true in options.

error TypeError: cssPlugin is not a function ↓

cause Using a named import like `import { cssPlugin }` instead of default export.

fix

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

error Error: The plugin 'esbuild-plugin-react18-css' is not compatible with this build tool (e.g., Vite). ↓

cause Using plugin outside ESBuild context.

fix

Only use in esbuild or tsup configuration.

error Error: Cannot read properties of undefined (reading 'css') ↓

cause Missing or misconfigured CSS/SCSS loader in the build chain.

fix

Ensure entry points reference .module.css or .module.scss files that are processed by the plugin.

Warnings

breaking v0.0.1 removed 'modules' and 'peerDependencies' – older configuration may break. ↓

fix Update to v0.0.4 and remove any manual peerDependencies or modules config.

gotcha The plugin generates class names without hash by default for easier overrides, which may cause conflicts in large projects. ↓

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

deprecated No known deprecations yet due to early version. ↓

fix Stay updated with releases.

gotcha The package is ESM-only; CommonJS require() will throw an error. ↓

fix Use import syntax or dynamic import().

gotcha If skipAutoPrefixer is false (default), autoprefixer must be installed separately. ↓

fix Install autoprefixer as a dependency, or set skipAutoPrefixer: true.

breaking The plugin only works with ESBuild or tools that support ESBuild plugins (e.g., tsup). Not compatible with webpack or Vite without additional wrappers. ↓

fix Use only in ESBuild-based build chains.

gotcha SCSS modules require node-sass or sass to be installed in the project, though not listed as a dependency. ↓

fix Install sass as a devDependency if using SCSS.

Install

npm install r18css

yarn add r18css

pnpm add r18css

Imports

default

wrong

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

correct

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

ESM-only package. Use default import.

CSSPluginOptions

wrong

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

correct

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

Type-only import for TypeScript.

CSSPlugin

wrong

import { default as cssPlugin } from 'esbuild-plugin-react18-css'

correct

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

The default export is a function; there is no named CSSPlugin export.

Quickstart

Shows how to use the plugin with ESBuild and tsup, including options like custom scoped name and global prefix.

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: 'myapp',
  })],
});

// With tsup:
// tsup.config.ts
import { defineConfig } from 'tsup';
export default defineConfig({
  esbuildPlugins: [cssPlugin()],
});