react-css-modules introduced a convention of using styleName attribute to reference CSS module. react-css-modules is a higher-order React component. It is using the styleName value to construct the className value at the run-time. This abstraction frees a developer from needing to reference the imported styles object when using CSS modules (What's the problem?). However, this approach has a measurable performance penalty (see Performance).

babel-plugin-react-css-modules solves the developer experience problem without impacting the performance.

The important metric here is the "Difference from the base benchmark". "base" is defined as using React with hardcoded className values. The lesser the difference, the bigger the performance impact.

Note: This benchmark suite does not include a scenario when babel-plugin-react-css-modules can statically construct a literal value at the build time. If a literal value of the className is constructed at the compile time, the performance is equal to the base benchmark.

Platform info:

• Darwin 16.1.0 x64
• Node.JS 7.1.0
• V8 5.4.500.36
• NODE_ENV=production
• Intel(R) Core(TM) i7-4870HQ CPU @ 2.50GHz x 8

View the ./benchmark.

Run the benchmark:

1. Builds index of all stylesheet imports per file (imports of files with .css or .scss extension).
2. Uses postcss to parse the matching CSS files into a lookup of CSS module references.
3. Iterates through all JSX element declarations.
4. Parses the styleName attribute value into anonymous and named CSS module references.
5. Finds the CSS class name matching the CSS module reference:
   • If styleName value is a string literal, generates a string literal value.
   • If styleName value is a jSXExpressionContainer, uses a helper function (getClassName) to construct the className value at the runtime.
6. Removes the styleName attribute from the element.
7. Appends the resulting className to the existing className value (creates className attribute if one does not exist).

Configure the options for the plugin within your .babelrc as follows:

Missing a configuration? Raise an issue.

Note: The default configuration should work out of the box with the css-loader.

To add support for different CSS syntaxes (e.g. SCSS), perform the following two steps:

1. Add the postcss syntax loader as a development dependency:

2. Add a filetypes syntax mapping to the Babel plugin configuration. For example for SCSS:

And optionally specify extra plugins:

NOTE: postcss-nested is added as an extra plugin for demonstration purposes only. It's not needed with postcss-scss because SCSS already supports nesting.

Postcss plugins can have options specified by wrapping the name and an options object in an array inside your config:

You can set your own attribute mapping rules using the attributeNames option.

It's an object, where keys are source attribute names and values are destination attribute names.

For example, the component from React Router has a activeClassName attribute to accept an additional class name. You can set "attributeNames": { "activeStyleName": "activeClassName" } to transform it.

The default styleName -> className transformation will not be affected by an attributeNames value without a styleName key. Of course you can use { "styleName": "somethingOther" } to change it, or use { "styleName": null } to disable it.

When babel-plugin-react-css-modules cannot resolve CSS module at a compile time, it imports a helper function (read Runtime styleName resolution). Therefore, you must install babel-plugin-react-css-modules as a direct dependency of the project.

If you'd like to get this working in React Native, you're going to have to allow custom import extensions, via a rn-cli.config.js file:

Remember, also, that the bundler caches things like plugins and presets. If you want to change your .babelrc (to add this plugin) then you'll want to add the --reset-cache flag to the end of the package command.

Anonymous reference can be used when there is only one stylesheet import.

Format: CSS module name.

Example:

Named reference