babel-plugin-react-css-modules


Transforms styleName to className using compile time CSS module resolution.

In contrast to react-css-modules, babel-plugin-react-css-modules has a lot smaller performance overhead (0-10% vs +50%; see Performance) and a lot smaller size footprint (less than 2kb vs 17kb react-css-modules + lodash dependency).

* CSS Modules
* Difference from react-css-modules
* Performance
* How does it work?
* Conventions
* Anonymous reference
* Named reference
* Configuration
* Configurate syntax loaders
* Installation
* Demo
* Example transpilations
* Anonymous styleName resolution
* Named styleName resolution
* Runtime styleName resolution
* Limitations
* Have a question or want to suggest an improvement?
* FAQ
* How to reference multiple CSS modules?
* How to live reload the CSS?

CSS Modules

CSS Modules are awesome! If you are not familiar with CSS Modules, it is a concept of using a module bundler such as webpack to load CSS scoped to a particular document. CSS module loader will generate a unique name for each CSS class at the time of loading the CSS document (Interoperable CSS to be precise). To see CSS Modules in practice, webpack-demo.

In the context of React, CSS Modules look like this:

``js
import React from 'react';
import styles from './table.css';

export default class Table extends React.Component {
render () {
return

`

Rendering the component will produce a markup similar to:

`js


`

and a corresponding CSS file that matches those CSS classes.

Awesome!

However, there are several several disadvantages of using CSS modules this way:

* You have to use camelCase CSS class names.
* You have to use styles object whenever constructing a className.
* Mixing CSS Modules and global CSS classes is cumbersome.
* Reference to an undefined CSS Module resolves to undefined without a warning.

babel-plugin-react-css-modules automates loading of CSS Modules using styleName property, e.g.

`js
import React from 'react';
import './table.css';

export default class Table extends React.Component {
render () {
return

`

Using babel-plugin-react-css-modules:

* You are not forced to use the camelCase naming convention.
* You do not need to refer to the styles object every time you use a CSS Module.
* There is clear distinction between global CSS and CSS modules, e.g.

`js


Difference from react-css-modules

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.

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.

|Name|Operations per second (relative margin of error)|Sample size|Difference from the base benchmark|
|---|---|---|---|
|Using className (base)|9551 (±1.47%)|587|-0%|
|react-css-modules|5914 (±2.01%)|363|-61%|
|babel-plugin-react-css-modules (runtime, anonymous)|9145 (±1.94%)|540|-4%|
|babel-plugin-react-css-modules (runtime, named)|8786 (±1.59%)|527|-8%|

> 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 × 8

View the ./benchmark.

Run the benchmark:

`bash
git clone git@github.com:gajus/babel-plugin-react-css-modules.git
cd ./babel-plugin-react-css-modules
npm install
npm run build
cd ./benchmark
npm install
NODE_ENV=production ./test
`

How does it work?

1. Builds index of all stylesheet imports per file (imports of files with .css or .scss extension).
1. Uses postcss to parse the matching CSS files.
1. Iterates through all JSX element declarations.
1. Parses the styleName attribute value into anonymous and named CSS module references.
1. 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.
1. Removes the styleName attribute from the element.
1. Appends the resulting className to the existing className value (creates className attribute if one does not exist).

Configuration

|Name|Description|Default|
|---|---|---|
|context|Must match webpack context configuration. css-loader inherits context values from webpack. Other CSS module implementations might use different context resolution logic.|process.cwd()|
|filetypes|Configure postcss syntax loaders like sugerss, LESS and SCSS. ||
|webpackHotModuleReloading|Enables hot reloading of CSS in webpack|false|
|generateScopedName|Refer to Generating scoped names|[path]___[name]__[local]___[hash:base64:5]|

Missing a configuration? Raise an issue.

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

$3

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:

`bash
npm install postcss-scss --save-dev
`

2. Add a filetype syntax mapping to the Babel plugin configuration

`json
"filetypes": {
".scss": "postcss-scss"
}
`

Installation

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.

`bash
npm install babel-plugin-react-css-modules --save
`

$3

`bash
git clone git@github.com:gajus/babel-plugin-react-css-modules.git
cd ./babel-plugin-react-css-modules/demo
npm install
webpack-dev-server
`

`bash
open http://localhost:8080/
`

Conventions

$3

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

Format: CSS module name.

Example:

`js
import './foo1.css';

// Imports "a" CSS module from ./foo1.css.


Format: [name of the import].[CSS module name].

Example:

`js
import foo from './foo1.css';
import bar from './bar1.css';

// Imports "a" CSS module from ./foo1.css.


When styleName is a literal string value, babel-plugin-react-css-modules resolves the value of className at the compile time.

Input:

`js
import './bar.css';

`

Output:

`js
import './bar.css';

`

$3

When a file imports multiple stylesheets, you must use a named reference.

> Have suggestions for an alternative behaviour?
> Raise an issue with your suggestion.

Input:

`js
import foo from './foo1.css';
import bar from './bar1.css';

`js
import foo from './foo1.css';
import bar from './bar1.css';

`

$3

When the value of styleName cannot be determined at the compile time, babel-plugin-react-css-modules inlines all possible styles into the file. It then uses getClassName helper function to resolve the styleName value at the runtime.

Input:

`js
import './bar.css';

`

Output:

`js
import _getClassName from 'babel-plugin-react-css-modules/dist/browser/getClassName';
import foo from './bar.css';

const _styleModuleImportMap = {
foo: {
a: 'bar__a',
b: 'bar__b'
}
};

`

Limitations

* Establish a convention for extending the styles object at the runtime

Have a question or want to suggest an improvement?

* Have a technical questions? Ask on Stack Overflow.
* Have a feature suggestion or want to report an issue? Raise an issues.
* Want to say hello to other babel-plugin-react-css-modules users? Chat on Gitter.

FAQ

$3

react-css-modules had an option allowMultiple. allowMultiple allows multiple CSS module names in a styleName declaration, e.g.

`js