How to dev

How to dev

How to set up CSS Modules with esbuild

In this article, I'll show how to configure CSS Modules with esbuild.

CSS Modules

It is a technic of making our styles scoped locally. I first encountered it while working on this SolidJS + esbuild. My understanding is that it's popular among developers using react.


My code is pretty simples. src/style.module.css:

.test {
  color: #66f;


import styles from "./style.module.css";

const header = document.createElement("h1");

header.innerHTML = "Hello world";
header.className = styles.test;



This is combined in a way that ensures no css class collision:

._test_1f4jo_1 {
    color: #66f;
<h1 class="_test_1f4jo_1">Hello world</h1>


Esbuild needs a plugin to support CSS modules. On the plugin list, there are 2 listed. I used esbuild-css-modules-plugin here. The dependencies needed to run it all successfully:

$ npm install --save-dev esbuild-css-modules-plugin esbuild

An additional dependency is needed to address a tiny dependency issue:

$ npm install --save-dev css-tree


For using a plugin with esbuild, we need a build script. build.js:

#!/usr/bin/env node

const cssModulesPlugin = require("esbuild-css-modules-plugin");

    logLevel: "info",
    entryPoints: ["src/index.js"],
    bundle: true,
    outfile: "dist/main.js",
    plugins: [cssModulesPlugin()],
  .catch(() => process.exit(1));

If you run chmod +x build.js, you will be able to run it:

$ ./build.js 

  dist/main.js  722b 

⚡ Done in 16ms


Video course

You can check out my course about esbuild.


In this article, we have seen how to configure CSS Modules with esbuild.

Interested in reading more such articles from Marcin Wosinek?

Support the author by donating an amount of your choice.

Share this
Proudly part of