esbuild SCSS Modules Plugin

1.1.1 verified Mon Apr 27 auth: no javascript

A plugin for esbuild that enables SCSS and CSS Modules support, allowing you to import .scss or .module.scss files and obtain CSS module class name mappings. Currently at version 1.1.1, it is actively maintained with a low release cadence. It offers features like CSS injection and minification (via cssnano) and supports esbuild's watch mode. Compared to alternatives like esbuild-css-modules-plugin, this one directly integrates SCSS compilation without needing additional loaders or plugins. Ships TypeScript types.

Common errors

error Error: Cannot find module 'cssnano' ↓

cause The minify option is enabled but cssnano is not installed.

fix

Install cssnano as a dev dependency: npm install --save-dev cssnano@~5.0.6

error TypeError: ScssModulesPlugin is not a function ↓

cause Default import used instead of named import.

fix

Use named import: import { ScssModulesPlugin } from 'esbuild-scss-modules-plugin'

error Module parse failed: Unexpected token (1:0) - You may need an appropriate loader to handle this file type. ↓

cause The plugin is not included in the esbuild plugins array, or the entry point is not using the plugin.

fix

Add the plugin to the plugins array and ensure entry points import .scss files.

Warnings

gotcha The plugin only processes .scss and .module.scss files; plain .css files are not handled. ↓

fix Use a separate esbuild CSS plugin for .css files or rename them to .scss.

gotcha When inject: false, CSS is output separately; you must handle the CSS output manually. ↓

fix Set inject: true to automatically inject CSS into JS bundle, or use the cssCallback to handle CSS.

gotcha The minify option requires cssnano to be installed as a peer dependency. ↓

fix Install cssnano: npm install cssnano@~5.0.6

deprecated Options typed in index.ts but not explicitly documented; checking source is needed for full list. ↓

fix Refer to the source file index.ts for all available options.

Install

npm install esbuild-scss-modules-plugin

yarn add esbuild-scss-modules-plugin

pnpm add esbuild-scss-modules-plugin

Imports

ScssModulesPlugin

wrong

import ScssModulesPlugin from 'esbuild-scss-modules-plugin'

correct

import { ScssModulesPlugin } from 'esbuild-scss-modules-plugin'

The package exposes a named export, not a default export.

ScssModulesPlugin (as default)

wrong

import ScssModulesPlugin from 'esbuild-scss-modules-plugin'

correct

import { ScssModulesPlugin } from 'esbuild-scss-modules-plugin'

There is no default export; only named.

ScssModulesPlugin (CJS require)

wrong

const ScssModulesPlugin = require('esbuild-scss-modules-plugin')

correct

const { ScssModulesPlugin } = require('esbuild-scss-modules-plugin')

CJS require should destructure the named export.

CSS modules types
```
import type { CSSModules } from 'esbuild-scss-modules-plugin'
```
TypeScript users may need to import the CSSModules type for module declarations.

Quickstart

Minimal setup showing how to use the plugin with esbuild, enabling CSS module support for .scss files and injecting styles into the bundle.

import esbuild from 'esbuild';
import { ScssModulesPlugin } from 'esbuild-scss-modules-plugin';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/index.js',
  plugins: [
    ScssModulesPlugin({
      inject: true,
      minify: false,
      localsConvention: 'camelCaseOnly',
    }),
  ],
});