How to configure esbuild to use css-modules and sass/scss for when bundling?

When building projects with esbuild, if you require support for CSS modules and processing SASS/SCSS, you must enhance esbuild's capabilities through plugins. esbuild natively supports bundling and minification of JavaScript and TypeScript, but handling CSS modules and SASS/SCSS necessitates additional configuration. Below are the steps to configure esbuild for these functionalities:

1. Install Required Packages

First, install esbuild and the necessary plugins for handling CSS and SASS. Open your terminal and run the following commands:

bash
npm install esbuild
npm install esbuild-plugin-sass
npm install @esbuild-plugins/css-modules

Here, esbuild-plugin-sass compiles SASS/SCSS files, and @esbuild-plugins/css-modules enables CSS modules functionality.

2. Configure esbuild

Next, create an esbuild configuration file or configure esbuild in your build script. The following is an example using the JavaScript API:

javascript
const esbuild = require('esbuild');
const sassPlugin = require('esbuild-plugin-sass');
const cssModulesPlugin = require('@esbuild-plugins/css-modules');

esbuild.build({
    entryPoints: ['src/index.js'], // Specify entry file
    bundle: true,                  // Enable bundling
    outdir: 'dist',                // Specify output directory
    plugins: [
        sassPlugin(),              // Add SASS/SCSS support plugin
        cssModulesPlugin({         // Configure CSS modules plugin
            localsConvention: 'camelCase', // Convert CSS class names to camelCase
            generateScopedName: '[name]__[local]___[hash:base64:5]', // Define the generated class name format
        })
    ]
}).catch(() => process.exit(1));

3. Use CSS Modules and SASS/SCSS

In your JavaScript or TypeScript files, import and use CSS modules as follows:

javascript
import styles from './style.module.scss';

console.log("Generated CSS class name:", styles.myClassName);

In this example, style.module.scss is a SASS file, which might look like:

scss
.myClassName {
    color: red;
}

With the CSS modules plugin, .myClassName is converted to a unique class name to avoid global naming conflicts.

4. Run the Build Script

Finally, execute your build script. esbuild processes the entry file and its dependencies, generating final output files in the dist directory. All SASS/SCSS files are compiled into CSS, and CSS class names are converted and generated according to CSS modules rules.

With this setup, esbuild is configured to support CSS modules and SASS/SCSS.