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.
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", // support multi target, just ['./dist', './build']
}]
]
}
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"]
}]
]
}
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
.
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
.
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.
This project is distributed under the MIT license.