Using CSS Modules with create-react-app

14 Jul 2020

Starting a new React project used to be a complicated process that involved setting up a build system, a code transpiler to convert modern JS code to code that is readable by all browsers, and a base directory structure. Create-react-app offers a modern build setup that comes pre-configured with everything we need to start building our React app. One feature is CSS Modules that is available in create-react-app from version 2 and later.

What are CSS Modules ?

Stylesheets in large apps can get quite messy and coming up with new class names for slightly different components can get hard really quick. A CSS module is a CSS file, but with a key difference: by default, when it is imported in a component every class name and animation inside that module is scoped locally to that component. This allows us to use any valid name for our classes, without worrying about conflicts with other class names in our application. In this post I will show you how to get started with CSS Modules and explain what happens when you use them.

How to use CSS Modules in CRA ?

To get started you will need an app generated with the create-react-app package (version 2 or later, but it is recommended to use the latest). To generate a project you can use:

$ npm i create-react-app -g
$ create-react-app my-app

or if you have npx installed:

$ npx create-react-app my-app

The way that CRA is set up is that to use CSS Modules first we have to rename all the CSS files from [name].css to [name].module.css . In the css file any valid class name is acceptable, but it’s recommend to use camelCase for classes with more than one word. The reason for this is that we will access these classes later as properties of a JS object (e.g. styles.someProperty), but it is not enforced (you can access with styles['some-property']). Next we can look at how to use them in the components. First we need to change the import:

// From
import './App.css';
// To
import styles from './App.module.css';

Note that we are importing something from the CSS file the same way we do from a JS file. This is because during our build step, the compiler would search through the App.module.css file that we’ve imported, then look through the JavaScript we’ve written and make the .customClass class accessible via styles.customClass. Now we can use the classes as properties from the object that we imported:

import React from 'react';

import styles from './App.module.css';

function App() {
	return <div className={styles.customClass}>Hello React!</div>;

export default App;

And that is it, you are ready to use CSS Modules...

But why do we need CSS Modules ?

Well as I mentioned in large project coming up with unique class names can be hard. CSS Modules enable you to use the same class wherever you want. Since the compiler handles the CSS it changes all the class names with different unique names in order make them locally available for that component. For example:

<!-- Normal class -->
<div class="customClass"></div>
<!-- Module class -->
<div class="App_customClass__28RXF"></div>

This means that we can have the customClass in multiple CSS files without worrying about conflicts between them.


This is not the only benefit of CSS Modules. You can find more about them in this great article. Hope this is helpful and as always - Happy coding.