PostCSS with CSS Modules and React

Updates

05/07/20 - The localIdentName property for css-loader is now a sub-property of the modules property.

02/10/18 - Looks like Create React App now adds support for CSS Modules

Quick Intro

CSS Modules are meant as a way to locally scope class and animation names to help prevent some of the downfalls of the default global scope that normal CSS is based on.

PostCSS provides a way to transform styles using JavaScript plugins.

Can we make them work together? Why would we want to? Let’s answer the second question first.

The Why

PostCSS has a deep, deep ecosystem, and of particular interest to me is the postcss-preset-env plugin. Using this plugin gets you access to the newest CSS features, and their polyfills, today. This role used to be filled by cssnext but this was recently deprecated, so what better time to explore postcss-preset-env?

An early issue I’ve had using CSS Modules has been its ‘variables’ syntax. While they definitely exist, I’m really not sold on the syntax, and CSS Variables are already in the spec so why are we re-inventing this particular wheel? I don’t think I’m alone in this feeling, other people seem to be asking how to use CSS Modules with the standard CSS Variables, so here we are.

Couple this with some fairly sweet future CSS functionality, and we’ve got reason enough to tie PostCSS together with CSS Modules.

The How

Alright lets get to it. I hope you’re ready for your node_modules directory to grow a fair bit, we’ve got some installing to do!

First up, getting CSS Modules to work at all in the context of your React application.

CSS Modules

Let’s get babel-plugin-react-css-modules (is there a longer npm package name?) installed. It has a runtime component, so it actually belongs in your dependencies rather than your devDependencies. Install it like this:

npm install babel-plugin-react-css-modules --save

Make sure your .babelrc or whatever equivalent you are using to configure Babel includes the new plugin:

plugins: [‘react-css-modules’]

And now we need to configure Webpack to tell it how to load in CSS files. We’ll need style-loader and css-loader for this one. These are regular devDependencies so make sure you install them as such.

npm install css-loader style-loader --save-dev

Now lets tell Webpack to use these loaders for CSS files. Add the following to your webpack.config.js

{
  test: /\.css$/,
  use: [
    { loader: 'style-loader' },
    {
      loader: 'css-loader',
      options: {
        modules: {
          localIdentName: '[path]___[name]__[local]___[hash:base64:5]',
        },
      },
    },
  ],
}

What’s up with that localIdentName? Good question! When you switch on the CSS Modules spec, css-loader will munge your css classes according to this ident. This means you can have two .button classes in your codebase and they wont conflict.

However this means that when you add a class name to your React component you’d need to know what css-loader is going to transform your class names into, right? Well that’s where babel-plugin-react-css-modules comes in. It’ll do the same munging of class names as css-loader, we just have to make sure they are configured to use the same method of munging.

The default value for this option in css-loader is different to babel-plugin-react-css-modules, so specifying it to be [path]__[name][local]__[hash:base64:5] fixes that.

Great, now in your React component you should be able to import the CSS file directly:

App.css

.app {
  border: 1px solid red;
}

App.jsx

import React from 'react';

import './App.css';

const App = () => (
  <div styleName="app">
    Hello, world!
  </div>
);

export default App;

The styleName property is babel-plugin-react-css-modules’s replacement for className, but you get used to it pretty quickly.

Assuming everything has worked, you’ll have class names that look like word soup:

PostCSS

And now for the fun stuff. Lots of modules to install, so lets get started:

npm install postcss postcss-import postcss-loader postcss-preset-env postcss-url --save-dev

We will need to change our webpack.config.js to make sure the postcss-loader gets used:

{
  test: /\.css$/,
  use: [
    { loader: 'style-loader' },
    {
      loader: 'css-loader',
      options: {
        importLoaders: 1,
        modules: {
          localIdentName: '[path]___[name]__[local]___[hash:base64:5]',
        },
      },
    },
    { loader: 'postcss-loader' }
  ],
}

And now we need a new postcss.config.js file

module.exports = {
  plugins: [
    require('postcss-import'),
    require('postcss-url'),
    require('postcss-preset-env')({
      browsers: 'last 2 versions',
      stage: 0,
    }),
  ],
};

Now we can try it out! Make a new colors.css file

:root {
  --errorRed: #e03030;
}

and change App.css to use it:

@import "../colors.css";

.app {
  border: 1px solid var(--errorRed);
}

How’s that style block looking?

Nice! You get the var() rule for browsers that support it, or the fallback for those that don’t.

Wrapping Up

Getting the right combination of modules to make this work was the real challenge on this one, the configuration itself was fairly easy.

If this doesn’t work for you, something is missing, or you think I’ve gone about this the wrong way, I’d love to hear from you in the comments.