Awesome
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:
Unlike the above, it supports both synchronous and asynchronous PostCSS plugins.
License
This project is distributed under the MIT license.