A short story about CSS modules

When I started to deal with web design, I began to work with HTML in combination of using the simplest CSS properties available, eg. changing colors and setting positions without any structure behind. This resulted in my stylesheets becoming confusing and sometimes conflicting with each other, maybe also because I was throwing around with !important rules.

Therefore I spent many hours on clearing my floating containers, as well as fixing problems in design with workarounds or nesting containers. Maybe I didn’t know how to do it better at this time. But honestly, I did not take CSS very seriously and it felt like it was the little unloved brother of HTML, which only responsibility is to provide pretty fonts and colors and force every single container to its specified position without taking care of other elements. No more, no less. At some point I discovered the possibility to create little but (related to my current knowledge at that time) impressive animations with the transition property. I started to change my mind: maybe there was a brighter future for CSS? And over the years, luckily I was proven to be right.

Today, there are plenty of code conventions, style guides and tools, like BEM, SMACSS or OOCSS. But there is one that catches me the most: CSS Modules. In short summary, instead of writing plain HTML, we are writing all of our markup in JavaScript, import CSS files and use their properties. The keyword here is locally scoped, so class names become similar to local variables in JavaScript. The CSS module itself is a just a normal .css file with local class names and is put through a compiler to come out the other side as a modified version of input CSS with renamed class names. The new CSS name is a combination from the name of the file it came from, the local class name and a random hash, eg. person_name_jx3k. The css-loader from webpack for example is one of those CSS modules compilers. But there’s more to it: the CSS modules actually has another hidden output, a JavaScript module that exports an object which maps all of your original class names to the renamed ones.

Take a look at this example:

The key name matches the original class name and gives back the renamed class. As you can see, CSS modules make it possible to start a new component without global styles that interfere with existing work. Here’s an example of how that might work in practice:

The rendered HTML output would be:

So the advantages of CSS modules are clear:

• CSS becomes modular and reusable.
• It avoids class names collisions. No polluting of the global scope anymore.
• JavaScript needs to specify CSS dependencies explicitly. You know exactly which class names are used where.

Jessica took an apprenticeship at Peerigon in 2019 to become a professional web developer. As part of her weekly routine, she publishes a blog post each week about what she has been doing and what she has learned.