esbuild-ssr-css-modules-plugin

0.1.32 verified Fri May 01 auth: no javascript

An esbuild plugin for bundling CSS Module files with support for both client-side and server-side rendering (SSR). Version 0.1.32 provides a straightforward way to generate CSS class name maps for server-side use while keeping class-scoped styles for client bundles. It integrates directly into esbuild's build pipeline and is part of the Goldstack monorepo, receiving updates as part of that project. Compared to alternatives like esbuild-css-modules-plugin, it is designed specifically for SSR workflows, automatically producing both CSS and JavaScript mapping files. The plugin has no direct runtime dependencies besides esbuild (peer dependency ^0.25.6), and its source is on GitHub within the Goldstack repository.

Common errors

error Error: The plugin 'esbuild-ssr-css-modules-plugin' is not supported in CommonJS. Use import() or switch to ESM. ↓

cause The package is ESM-only and cannot be required with `require()`.

fix

Change your script to a module (set "type": "module" in package.json) and use import esbuildSsrCssModulesPlugin from 'esbuild-ssr-css-modules-plugin'.

error TypeError: options.outdir is deprecated. Use options.outputDir instead. ↓

cause Using deprecated `outdir` option in plugin configuration.

fix

Replace outdir: './path' with outputDir: './path'.

error Build failed with 1 error: error: No matching files found for pattern 'src/**/*.module.css' ↓

cause The plugin's source filter expects files matching `*.module.css` or `*.module.scss`, but the glob pattern used in the plugin may not match if the entry point doesn't include those files.

fix

Ensure your entry point imports CSS module files with the .module.css extension, or adjust the plugin's filter option to match your file names.

Warnings

gotcha The plugin only processes files ending with .module.css or .module.scss. Regular .css files are ignored. ↓

fix Rename your CSS module files to follow the .module.css or .module.scss naming convention.

deprecated As of version 0.1.30, the 'outdir' option is deprecated and will be removed in a future version. Use 'outputDir' instead. ↓

fix Replace `outdir` with `outputDir` in plugin options.

breaking In version 0.1.25, the default value for the 'naming' option changed from '[name].module' to '[name]-[hash].module'. This can cause unexpected file names if you are relying on the old default. ↓

fix Explicitly set the 'naming' option to '[name].module' if you need the old naming pattern.

gotcha The plugin requires esbuild ^0.25.6 as a peer dependency. Using an older esbuild version may lead to undefined behavior or missing features. ↓

fix Ensure your project has esbuild at version ^0.25.6 installed.

gotcha When using the plugin in a monorepo with multiple esbuild builds, each build instance should have its own plugin instance to avoid cross-build interference. ↓

fix Create a new plugin instance inside each esbuild.build call, not as a shared singleton.

Install

npm install esbuild-ssr-css-modules-plugin

yarn add esbuild-ssr-css-modules-plugin

pnpm add esbuild-ssr-css-modules-plugin

Imports

default

wrong

const esbuildSsrCssModulesPlugin = require('esbuild-ssr-css-modules-plugin')

correct

import esbuildSsrCssModulesPlugin from 'esbuild-ssr-css-modules-plugin'

Package is ESM-only; CommonJS require is not supported.

esbuildSsrCssModulesPlugin (named export)

wrong

import { plugin } from 'esbuild-ssr-css-modules-plugin'

correct

import { esbuildSsrCssModulesPlugin } from 'esbuild-ssr-css-modules-plugin'

The only named export is the plugin itself, not a generic 'plugin' name.

PluginOptions

wrong

import { PluginOptions } from 'esbuild-ssr-css-modules-plugin'

correct

import type { PluginOptions } from 'esbuild-ssr-css-modules-plugin'

PluginOptions is a TypeScript type; use `import type` to avoid runtime inclusion.

Quickstart

Uses esbuild with the SSR CSS Modules plugin to bundle an app while extracting CSS module mappings for server use.

import esbuild from 'esbuild';
import esbuildSsrCssModulesPlugin from 'esbuild-ssr-css-modules-plugin';
import path from 'path';

await esbuild.build({
  entryPoints: ['./src/app.js'],
  bundle: true,
  outdir: './dist',
  plugins: [
    esbuildSsrCssModulesPlugin({
      // Generate separate CSS and JS mapping files for SSR
      generate: {
        css: true,
        js: true,
      },
      // Output directory for the generated files
      outdir: './dist/css-modules',
      // Map files naming pattern
      naming: '[name]-[hash].module',
    }),
  ],
});