postcss-modules

What is postcss-modules?

The postcss-modules package is a PostCSS plugin that enables CSS Modules, a technique for locally scoping CSS by automatically creating a unique classname of the format [filename]__[local classname]__[hash]. This helps in avoiding global scope pollution in CSS and makes component-based development easier and more maintainable.

What are postcss-modules's main functionalities?

Local Scope for CSS Classes

This feature automatically scopes class names locally rather than globally. This is done by appending a unique hash to each class name, which makes them unique across the project. This prevents styles from leaking into other parts of the application unintentionally.

/* Input CSS */
.className {
  color: red;
}

/* Output CSS */
.fileName__className__hash {
  color: red;
}

Composition of Styles

This feature allows CSS classes to compose from other classes, potentially from different files. This promotes reusability of CSS styles and helps in maintaining a cleaner and more organized stylesheet architecture.

/* Input CSS */
.className {
  composes: anotherClass from './anotherStyle.css';
  color: red;
}

/* Output CSS */
.fileName__className__hash {
  color: red;
}
.fileName__anotherClass__hash {
  /* styles from anotherClass */
}

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.

README

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

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 jsonFileName = cssFileName + '.json';
      fs.writeFileSync(jsonFileName, JSON.stringify(json));
    }
  });
]);

Generate custom classes with the generateScopedName callback:

postcss([
  require('postcss-modules')({
    getJSON: function(cssFileName, json) {},
    generateScopedName: function(name, filename, css) {
      const i         = css.indexOf('.' + name);
      const numLines  = css.substr(0, i).split(/[\r\n]/).length;
      const 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

TODO

• Example
• Importing/exporting values

Changelog

0.1.0

Initial version