{"id":25448,"library":"esbuild-ssr-css-modules-plugin","title":"esbuild-ssr-css-modules-plugin","description":"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.","status":"active","version":"0.1.32","language":"javascript","source_language":"en","source_url":"https://github.com/goldstack/goldstack","tags":["javascript","node","css modules","esbuild","ssr","css"],"install":[{"cmd":"npm install esbuild-ssr-css-modules-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-ssr-css-modules-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-ssr-css-modules-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; plugin relies on esbuild plugin API to intercept CSS module files.","package":"esbuild","optional":false}],"imports":[{"note":"Package is ESM-only; CommonJS require is not supported.","wrong":"const esbuildSsrCssModulesPlugin = require('esbuild-ssr-css-modules-plugin')","symbol":"default","correct":"import esbuildSsrCssModulesPlugin from 'esbuild-ssr-css-modules-plugin'"},{"note":"The only named export is the plugin itself, not a generic 'plugin' name.","wrong":"import { plugin } from 'esbuild-ssr-css-modules-plugin'","symbol":"esbuildSsrCssModulesPlugin (named export)","correct":"import { esbuildSsrCssModulesPlugin } from 'esbuild-ssr-css-modules-plugin'"},{"note":"PluginOptions is a TypeScript type; use `import type` to avoid runtime inclusion.","wrong":"import { PluginOptions } from 'esbuild-ssr-css-modules-plugin'","symbol":"PluginOptions","correct":"import type { PluginOptions } from 'esbuild-ssr-css-modules-plugin'"}],"quickstart":{"code":"import esbuild from 'esbuild';\nimport esbuildSsrCssModulesPlugin from 'esbuild-ssr-css-modules-plugin';\nimport path from 'path';\n\nawait esbuild.build({\n  entryPoints: ['./src/app.js'],\n  bundle: true,\n  outdir: './dist',\n  plugins: [\n    esbuildSsrCssModulesPlugin({\n      // Generate separate CSS and JS mapping files for SSR\n      generate: {\n        css: true,\n        js: true,\n      },\n      // Output directory for the generated files\n      outdir: './dist/css-modules',\n      // Map files naming pattern\n      naming: '[name]-[hash].module',\n    }),\n  ],\n});","lang":"javascript","description":"Uses esbuild with the SSR CSS Modules plugin to bundle an app while extracting CSS module mappings for server use."},"warnings":[{"fix":"Rename your CSS module files to follow the .module.css or .module.scss naming convention.","message":"The plugin only processes files ending with .module.css or .module.scss. Regular .css files are ignored.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Replace `outdir` with `outputDir` in plugin options.","message":"As of version 0.1.30, the 'outdir' option is deprecated and will be removed in a future version. Use 'outputDir' instead.","severity":"deprecated","affected_versions":">=0.1.30 <0.2.0"},{"fix":"Explicitly set the 'naming' option to '[name].module' if you need the old naming pattern.","message":"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.","severity":"breaking","affected_versions":">=0.1.25"},{"fix":"Ensure your project has esbuild at version ^0.25.6 installed.","message":"The plugin requires esbuild ^0.25.6 as a peer dependency. Using an older esbuild version may lead to undefined behavior or missing features.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Create a new plugin instance inside each esbuild.build call, not as a shared singleton.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Change your script to a module (set `\"type\": \"module\"` in package.json) and use `import esbuildSsrCssModulesPlugin from 'esbuild-ssr-css-modules-plugin'`.","cause":"The package is ESM-only and cannot be required with `require()`.","error":"Error: The plugin 'esbuild-ssr-css-modules-plugin' is not supported in CommonJS. Use import() or switch to ESM."},{"fix":"Replace `outdir: './path'` with `outputDir: './path'`.","cause":"Using deprecated `outdir` option in plugin configuration.","error":"TypeError: options.outdir is deprecated. Use options.outputDir instead."},{"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.","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.","error":"Build failed with 1 error: error: No matching files found for pattern 'src/**/*.module.css'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}