postcss-modules

postcss-modules

A PostCSS plugin to use CSS Modules everywhere. Not only at the client side.

What is this? For example, you have the following CSS:

/* styles.css */
:global .page {
    padding: 20px;
}

.title {
    composes: title from "./mixins.css";
    color: green;
}

.article {
    font-size: 16px;
}

/* mixins.css */
.title {
    color: black;
    font-size: 40px;
}

.title:hover {
    color: red;
}

After the transformation it will become like this:

._title_116zl_1 {
    color: black;
    font-size: 40px;
}

._title_116zl_1:hover {
    color: red;
}

.page {
    padding: 20px;
}

._title_xkpkl_5 {
    color: green;
}

._article_xkpkl_10 {
    font-size: 16px;
}

And the plugin will give you a JSON object for transformed classes:

{
  "title": "_title_xkpkl_5 _title_116zl_1",
  "article": "_article_xkpkl_10",
}

Usage

By default, a JSON file with exported classes will be placed next to corresponding CSS. But you have a freedom to make everything you want with exported classes, just use the getJSON callback. For example, save data about classes into a corresponding JSON file:

postcss([
  require('postcss-modules')({
    getJSON: function(cssFileName, json) {
      var path          = require('path');
      var cssName       = path.basename(cssFileName, '.css');
      var jsonFileName  = path.resolve('./build' + cssName + '.json');
      fs.writeFileSync(jsonFileName, JSON.stringify(json));
    }
  });
]);

Generate custom classes with the generateScopedName callback:

postcss([
  require('postcss-modules')({
    generateScopedName: function(name, filename, css) {
      var path      = require('path');
      var i         = css.indexOf('.' + name);
      var numLines  = css.substr(0, i).split(/[\r\n]/).length;
      var file      = path.basename(filename, '.css');

      return '_' + file + '_' + numLines + '_' + name;
    }
  });
]);

See PostCSS docs for examples for your environment and don't forget to run

npm install --save-dev postcss-modules

Changelog

0.3.0

• Fixed processing for imported CSS
• Added default callback for saving exported JSON

Similar packages

Other packages similar to postcss-modules

css-loader

css-loader is a webpack loader that interprets @import and url() like import/require() and will resolve them. It also offers modules functionality similar to postcss-modules, where it localizes CSS by default using similar scoping rules. Compared to postcss-modules, css-loader is tightly integrated with webpack's module system, which might be preferable in webpack-based projects.

styled-components

styled-components is a library for React and React Native that allows CSS to be written inside JavaScript files by tagging template literals. This approach scopes styles by generating unique class names at runtime. Unlike postcss-modules, styled-components embeds styles directly into components, which can enhance runtime performance and offers enhanced theming capabilities.