README.md

Babel PostCSS Transform

A Babel plugin to process CSS files via PostCSS.

Using PostCSS Modules, it can transform:

import styles from './styles';

.example { color: cyan; }

Into an object that has properties mirroring the style names:

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

Configuration

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

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

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

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

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": [
    ["transform-postcss", {
      "config": "configuration/postcss.config.js"
    }]
  ]
}

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

{
  "plugins": [
    ["transform-postcss", {
      "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. It is expected that you transform your CSS using the same postcss.config.js file as the one used by this transform. We recommend:

• postcss-cli (v3 or later)
• gulp-postcsssrc

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.

Using with Browserify & Watchify

This will work well with the babelify transform, but if you're using watchify, you will want to add the relateify transform in order to ensure that changes to CSS files rebuild the appropriate JS files.

Caching

This module caches the results of the compilation of CSS files and stores the cache in a directory under /tmp/bptp-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.

Prior Art

This plugin is based of the work of:

• css-modules-transform
• css-modules-require-hook

Unlike the above, it supports both synchronous and asynchronous PostCSS plugins.

License

This project is distributed under the MIT license.