babel-plugin-postcss-css-modules

Babel CSS Modules by PostCSS

Babel Plugin to enjoy css module & process CSS file via PostCSS

import styles from './styles';

.example { color: cyan; }

Into an object that has properties mirroring the style names:

var styles = {"example": "_example_amfqe_1"};

Forked from: babel-plugin-transform-postcss

And Why: https://github.com/wbyoung/babel-plugin-transform-postcss/issues/89

Yes, I need to keep import/require declaration in some case when I make public components on npm which is used in project with create-react-app. Thanks to babel-plugin-transform-postcss.

Usage

Install the transform as well as postcss and any PostCSS plugins you want to use:

npm install --save-dev \
  babel-plugin-postcss-css-modules \
  postcss \
  postcss-modules

Add the transform to your babel configuration, i.e. .babelrc:

{
  "presets": [
    ["env", { "targets": { "node": "current" }}]
  ],
  "plugins": [
    "postcss-css-modules"
  ]
}

Create a postcss.config.js:

module.exports = (ctx) => ({
  plugins: [
    require('postcss-modules')({
      getJSON: ctx.extractModules || (() => {}),
    }),
  ],
});

You can also specify a location to load your postcss.config.js from in the options in your Babel configuration, i.e. .babelrc:

{
  "plugins": [
    ["postcss-css-modules", {
      "config": "configuration/postcss.config.js",
      "keep": true,
      "from": "./src",
      "to": "./dist",
    }]
  ]
}

Use "keep": true to keep import/require declaration. from & to should be given when need to output css file, they can be absolute path or relative path with root (default to process.cwd()).

By default we look for .css files, but you can also specify the extensions we should look for:

{
  "plugins": [
    ["postcss-css-modules", {
      "config": "configuration/postcss.config.js",
      "extensions": [".scss"]
    }]
  ]
}

Details

The transform will transform all imports & require statements that have a .css extension and run them through postcss. To determine the PostCSS config, it uses postcss-load-config with additional context values. One of those config values, extractModules should be invoked in order to define the value of the resulting import.

No CSS is actually included in the resulting JavaScript.

I recommend to use "keep": true in this plugin's options to keep import/requre declaration that your webpack can also bundle css file easily. However, webpack also should handle css file transform with the same postcss.config.js.

Notes: Without webpack, when you just use babel-cli with this plugin, you should set form & to options to make sure css file output.

Without "keep": true, It is expected that you transform your CSS using the same postcss.config.js file as the one used by this transform.

Finally, it's worth noting that this transform also adds a comment to the generated code indicating the related CSS file so that it can be processed by other tools, i.e. relateify.

PostCSS Load Config Context

extractModules(_: any, modules: object)

This option is a function that may be passed directly on to postcss-modules as the getJSON argument. Other uses, while unlikely, are permittable, as well.

The function accepts two arguments. The transform uses only the second value passed to the function. That value is the object value that replaces the import/require.

Cache

This module caches the results of the compilation of CSS files and stores the cache in a directory under /tmp/bppcm-UNIQUE_ID. The cache is only invalidated when the CSS file contents change and not when the postcss.config.js file changes (due to limitations at the time of implementation). Try removing the cache if you're not seeing expected changes.

License

This project is distributed under the MIT license.