|
| 1 | +# babel-plugin-react-css-modules |
| 2 | + |
| 3 | +[](https://travis-ci.org/gajus/babel-plugin-react-css-modules) |
| 4 | +[](https://www.npmjs.org/package/babel-plugin-react-css-modules) |
| 5 | +[](https://github.com/gajus/canonical) |
| 6 | +[](https://twitter.com/kuizinas) |
| 7 | + |
| 8 | +<img src='./.README/babel-plugin-react-css-modules.png' height='150' /> |
| 9 | + |
| 10 | +Transforms `styleName` to `className` using compile time [CSS module](https://github.com/css-modules/css-modules) resolution. |
| 11 | + |
| 12 | +In contrast to [`react-css-modules`](https://github.com/gajus/react-css-modules), `babel-plugin-react-css-modules` has a loot smaller performance overhead (0-10% vs +50%; see [Performance](#performance)) and a lot smaller size footprint (less than 2kb vs 17kb reaact-css-modules + lodash dependency). |
| 13 | + |
| 14 | +* [Background](#background) |
| 15 | +* [Performance](#performance) |
| 16 | +* [How does it work?](#how-does-it-work) |
| 17 | +* [Conventions](#conventions) |
| 18 | + * [Named reference](#named-reference) |
| 19 | +* [Configuration](#configuration) |
| 20 | +* [Example transpilations](#example-transpilations) |
| 21 | + * [Anonymous `styleName` resolution](#anonymous-stylename-resolution) |
| 22 | + * [Named `styleName` resolution](#named-stylename-resolution) |
| 23 | + * [Runtime `styleName` resolution](#runtime-stylename-resolution) |
| 24 | +* [Limitations](#limitations) |
| 25 | +* [Have a question or want to suggest an improvement?](#have-a-question-or-want-to-suggest-an-improvement) |
| 26 | + |
| 27 | +## Background |
| 28 | + |
| 29 | +[`react-css-modules`](https://github.com/gajus/react-css-modules) introduced a convention of using `styleName` attribute to reference [CSS module](https://github.com/css-modules/css-modules). `react-css-modules` is a higher-order [React](https://facebook.github.io/react/) component. It is using the `styleName` value to construct the `className` 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?](https://github.com/gajus/react-css-modules#whats-the-problem)). However, this approach has a measurable performance penalty at the cost of better developer experience (DX). |
| 30 | + |
| 31 | +`babel-plugin-react-css-modules` solves the DX problem without impacting the performance. |
| 32 | + |
| 33 | +## Performance |
| 34 | + |
| 35 | +The important metric here is "Difference from base" (DFB). "base" is defined as using React with hardcoded `className` values. The lesser the DFB value, the bigger the performance impact. |
| 36 | + |
| 37 | +> Note: |
| 38 | +> This benchmark suite does not include a scenario when `babel-plugin-react-css-modules` can statically construct the value of `className`. |
| 39 | +> If a literal value of the `className` is constructed at the compile time, the performance is equal to the base benchmark. |
| 40 | +
|
| 41 | +|Name|Operations per second (relative margin of error)|Sample size|Difference from the base benchmark| |
| 42 | +|---|---|---|---| |
| 43 | +|Using className (base)|8556 (±1.59)|546|-0%| |
| 44 | +|Using styleName with react-css-modules|5204 (±1.84)|335|-64%| |
| 45 | +|Using styleName with babel-plugin-react-css-modules (runtime anonymous resolution)|7821 (±1.89)|481|-9%| |
| 46 | +|Using styleName with babel-plugin-react-css-modules (runtime named resolution)|8155 (±1.63)|499|-4%| |
| 47 | + |
| 48 | +> Platform info: |
| 49 | +> Darwin 16.1.0 x64 |
| 50 | +> Node.JS 7.1.0 |
| 51 | +> V8 5.4.500.36 |
| 52 | +> NODE_ENV=production |
| 53 | +> Intel(R) Core(TM) i7-4870HQ CPU @ 2.50GHz × 8 |
| 54 | +
|
| 55 | +View the [./benchmark](./benchmark). |
| 56 | + |
| 57 | +Run the benchmark: |
| 58 | + |
| 59 | +```bash |
| 60 | +git clone [email protected]:gajus/babel-plugin-react-css-modules.git |
| 61 | +cd ./babel-plugin-react-css-modules |
| 62 | +npm install |
| 63 | +npm run build |
| 64 | +cd ./benchmark |
| 65 | +npm install |
| 66 | +NODE_ENV=production ./test |
| 67 | +``` |
| 68 | + |
| 69 | +## How does it work? |
| 70 | + |
| 71 | +1. Builds index of all stylesheet imports per file. |
| 72 | +1. Uses [postcss](https://github.com/postcss/postcss) to parse the matching CSS files. |
| 73 | +1. Iterates through all [JSX](https://facebook.github.io/react/docs/jsx-in-depth.html) element declarations. |
| 74 | +1. Uses the `styleName` value to resolve the generated CSS class name of the CSS module. |
| 75 | + * If `styleName` value is a string literal, generates a string literal value. |
| 76 | + * If `styleName` value is non-string (variable, condition, etc.), uses a helper function to construct `className` value at the runtime. |
| 77 | +1. Removes the `styleName` attribute from the element. |
| 78 | +1. Appends the resulting `className` to the existing `className` value (or creates `className` attribute if one does not exist). |
| 79 | + |
| 80 | +## Configuration |
| 81 | + |
| 82 | +|Name|Description|Default| |
| 83 | +|---|---|---| |
| 84 | +|`generateScopedName`|Refer to [Generating scoped names](https://github.com/css-modules/postcss-modules#generating-scoped-names)|N/A (delegates default resolution to [postcss-modules](https://github.com/css-modules/postcss-modules))| |
| 85 | + |
| 86 | +Missing a configuration? [Raise an issue](https://github.com/gajus/babel-plugin-react-css-modules/issues/new?title=New%20configuration:). |
| 87 | + |
| 88 | +## Conventions |
| 89 | + |
| 90 | +### Named reference |
| 91 | + |
| 92 | +Named reference is used to refer to a specific stylesheet import. |
| 93 | + |
| 94 | +Format: `[name of the import].[CSS module name]`. |
| 95 | + |
| 96 | +Example: |
| 97 | + |
| 98 | +```js |
| 99 | +import foo from './foo1.css'; |
| 100 | +import bar from './bar1.css'; |
| 101 | + |
| 102 | +// Imports "a" CSS module from ./foo1.css. |
| 103 | +<div styleName="foo.a"></div>; |
| 104 | + |
| 105 | +// Imports "a" CSS module from ./bar1.css. |
| 106 | +<div styleName="bar.a"></div>; |
| 107 | +``` |
| 108 | + |
| 109 | +## Example transpilations |
| 110 | + |
| 111 | +### Anonymous `styleName` resolution |
| 112 | + |
| 113 | +When `styleName` is a literal string value, `babel-plugin-react-css-modules` resolves the value of `className` at the compile time. |
| 114 | + |
| 115 | +Input: |
| 116 | + |
| 117 | +```js |
| 118 | +import './bar.css'; |
| 119 | + |
| 120 | +<div styleName="a"></div>; |
| 121 | + |
| 122 | +``` |
| 123 | + |
| 124 | +Output: |
| 125 | + |
| 126 | +```js |
| 127 | +import './bar.css'; |
| 128 | + |
| 129 | +<div className="bar___a"></div>; |
| 130 | + |
| 131 | +``` |
| 132 | + |
| 133 | +### Named `styleName` resolution |
| 134 | + |
| 135 | +When file imports multiple stylesheets, you must use a [named reference](#named-reference). |
| 136 | + |
| 137 | +Input: |
| 138 | + |
| 139 | +```js |
| 140 | +import foo from './foo1.css'; |
| 141 | +import bar from './bar1.css'; |
| 142 | + |
| 143 | +<div styleName="foo.a"></div>; |
| 144 | +<div styleName="bar.a"></div>; |
| 145 | +``` |
| 146 | + |
| 147 | +Output: |
| 148 | + |
| 149 | +```js |
| 150 | +import foo from './bar.css'; |
| 151 | + |
| 152 | +<div className="bar___a"></div>; |
| 153 | + |
| 154 | +``` |
| 155 | + |
| 156 | +### Runtime `styleName` resolution |
| 157 | + |
| 158 | +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. |
| 159 | + |
| 160 | +Input: |
| 161 | + |
| 162 | +```js |
| 163 | +import './bar.css'; |
| 164 | + |
| 165 | +<div styleName={Math.random() > .5 ? 'a' : 'b'}></div>; |
| 166 | + |
| 167 | +``` |
| 168 | + |
| 169 | +Output: |
| 170 | + |
| 171 | +```js |
| 172 | +import _getClassName from 'babel-plugin-react-css-modules/dist/browser/getClassName'; |
| 173 | +import foo from './bar.css'; |
| 174 | + |
| 175 | +const _styleModuleImportMap = { |
| 176 | + foo: { |
| 177 | + a: 'bar__a', |
| 178 | + b: 'bar__b' |
| 179 | + } |
| 180 | +}; |
| 181 | + |
| 182 | +<div styleName={_getClassName(Math.random() > .5 ? 'a' : 'b', _styleModuleImportMap)}></div>; |
| 183 | + |
| 184 | +``` |
| 185 | + |
| 186 | +## Limitations |
| 187 | + |
| 188 | +* [Establish a convention for extending the styles object at the runtime](https://github.com/gajus/babel-plugin-react-css-modules/issues/1) |
| 189 | + |
| 190 | +## Have a question or want to suggest an improvement? |
| 191 | + |
| 192 | +* Have a technical questions? http://stackoverflow.com/questions/ask?tags=babel-plugin-react-css-modules |
| 193 | +* Have a feature suggestion or want to report an issue? https://github.com/gajus/babel-plugin-react-css-modules/issues |
| 194 | +* Want to say hello to other `babel-plugin-react-css-modules` users? https://gitter.im/babel-plugin-react-css-modules |
0 commit comments