Success StoriesBlogContact
two books about css modules and a smartphone on top
Tutorials |

A short story about CSS modules

Jessica Schneck

March 1, 2019

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:

.name {
    background: hotpink;
// "hidden" person.js module

module.exports = {
    name: "person_name_jx3k" // <-- that's the generated class name

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:

import person form "./person.css";

element.innerHTML = `<h1 class="${}">Name</h1>`;

The rendered HTML output would be:

<h1 class="person_name_jx3k">Name</h1>

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.

What makes Peerigon workshops so special? Click to find out!

To the workshop benefits

CSS Modules





Web Development

Read also

Klara, 11/22/2023

Peerigon goes purple

#PurpleLightUp 2022


company culture


Go to Blogarticle

Irena, 05/23/2023

Supporting the queer Community in Augsburg: Diversity Day 2023



CSD Augsburg

Queer Community

Company Culture

Go to Blogarticle

Moritz Jacobs, 03/23/2023

Unit Testing Licenses: Monitoring the legality of your node_modules with Jest

open source licenses

unit testing


Go to Blogarticle

Peerigon: the company for bespoke software development.

Peerigon GmbH

Werner-von-Siemens-Straße 6
86159 Augsburg
+49 821 907 80 86 0
mail peerigon
BCorpkununu top company 2022


IT staff augmentation servicesUX/UI DesignCustom Software DevelopmentSoftware Development ConsultingFull Stack Training
BlogSuccess StoriesContactWhy use TypeScript?

© 2023 Peerigon

Privacy PolicyLegal NoticeContactPress

Do you already know Konsens, our free online tool?