Registry / web-framework / esbuild-ssr-css-modules-plugin

esbuild-ssr-css-modules-plugin

library0.1.32jsnpmunverified

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.

web-framework

npm install esbuild-ssr-css-modules-plugin

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-SSR-CSS-MO

esbuild-ssr-css-modules-plugin

web-frameworkjavascriptv0.1.32

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

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

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

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

esbuildSsrCssModulesPlugin (named export)

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

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

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

PluginOptions

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

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

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

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

Debug

Known issues

gotchaThe 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.

affects: >=0.1.0

deprecatedAs 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.

affects: >=0.1.30 <0.2.0

breakingIn 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.

affects: >=0.1.25

gotchaThe 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.

affects: >=0.1.0

gotchaWhen 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.

affects: >=0.1.0

Errors

Common errors & fixes

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

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'`.

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

Using deprecated `outdir` option in plugin configuration.

fix

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

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

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.

Upgrade

Version history

0.1.32latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency; plugin relies on esbuild plugin API to intercept CSS module files.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/goldstack/goldstack ↗

packagehttps://www.npmjs.com/package/esbuild-ssr-css-modules-plugin ↗