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.

CSS Modules





Web Development

Weitere Themen

Irena Reitz, Celestine Auburger, Leonhard Melzer, 05/18/2021

Towards fairness: calculating the Peerigon Gender Pay Gap



Company Culture

Zum Blogartikel

Tanner Hoisington, 04/20/2021

Exploring various voting systems with Konsens

voting systems

ranked choice

positional vote

simple plurality


Zum Blogartikel

Moritz Jacobs, 02/12/2021

A guide to CSS units — pt. 4: angles, time, dpi and values without units

CSS units

CSS angles

CSS time



Zum Blogartikel

Wir sind Peerigon, eine Agentur für Softwareentwicklung.

Peerigon GmbH
Werner-von-Siemens-Straße 6
86159 Augsburg
+49 821 907 80 86 0

mail peerigon


Full-stack ConsultingSoftware DevelopmentProgramming WorkshopsTeam Support
BlogSuccess StoriesContactgo digital funding

© 2021 Peerigon

Privacy PolicyLegal NoticePress