You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+83-2Lines changed: 83 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,8 @@ Transforms `styleName` to `className` using compile time [CSS module](https://gi
12
12
13
13
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).
14
14
15
-
*[Background](#background)
15
+
*[CSS Modules](#css-modules)
16
+
*[Difference from `react-css-modules`](#difference-from-react-css-modules)
16
17
*[Performance](#performance)
17
18
*[How does it work?](#how-does-it-work)
18
19
*[Conventions](#conventions)
@@ -27,7 +28,87 @@ In contrast to [`react-css-modules`](https://github.com/gajus/react-css-modules)
27
28
*[Limitations](#limitations)
28
29
*[Have a question or want to suggest an improvement?](#have-a-question-or-want-to-suggest-an-improvement)
29
30
30
-
## Background
31
+
## CSS Modules
32
+
33
+
[CSS Modules](https://github.com/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](http://webpack.github.io/docs/) 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](https://github.com/css-modules/icss) to be precise). To see CSS Modules in practice, [webpack-demo](https://css-modules.github.io/webpack-demo/).
34
+
35
+
In the context of React, CSS Modules look like this:
36
+
37
+
```js
38
+
importReactfrom'react';
39
+
importstylesfrom'./table.css';
40
+
41
+
exportdefaultclassTableextendsReact.Component {
42
+
render () {
43
+
return<div className={styles.table}>
44
+
<div className={styles.row}>
45
+
<div className={styles.cell}>A0</div>
46
+
<div className={styles.cell}>B0</div>
47
+
</div>
48
+
</div>;
49
+
}
50
+
}
51
+
52
+
```
53
+
54
+
Rendering the component will produce a markup similar to:
55
+
56
+
```js
57
+
<div class="table__table___32osj">
58
+
<div class="table__row___2w27N">
59
+
<div class="table__cell___1oVw5">A0</div>
60
+
<div class="table__cell___1oVw5">B0</div>
61
+
</div>
62
+
</div>
63
+
64
+
```
65
+
66
+
and a corresponding CSS file that matches those CSS classes.
67
+
68
+
Awesome!
69
+
70
+
However, there are several several disadvantages of using CSS modules this way:
71
+
72
+
* You have to use `camelCase` CSS class names.
73
+
* You have to use `styles` object whenever constructing a `className`.
74
+
* Mixing CSS Modules and global CSS classes is cumbersome.
75
+
* Reference to an undefined CSS Module resolves to `undefined` without a warning.
76
+
77
+
`babel-plugin-react-css-modules` automates loading of CSS Modules using `styleName` property, e.g.
78
+
79
+
```js
80
+
importReactfrom'react';
81
+
import'./table.css';
82
+
83
+
exportdefaultclassTableextendsReact.Component {
84
+
render () {
85
+
return<div styleName='table'>
86
+
<div styleName='row'>
87
+
<div styleName='cell'>A0</div>
88
+
<div styleName='cell'>B0</div>
89
+
</div>
90
+
</div>;
91
+
}
92
+
}
93
+
94
+
```
95
+
96
+
Using `babel-plugin-react-css-modules`:
97
+
98
+
* You are not forced to use the `camelCase` naming convention.
99
+
* You do not need to refer to the `styles` object every time you use a CSS Module.
100
+
* There is clear distinction between global CSS and CSS modules, e.g.
* You are warned when `styleName` refers to an undefined CSS Module ([`errorWhenNotFound`](#errorwhennotfound) option).
108
+
* You can enforce use of a single CSS module per `ReactElement` ([`allowMultiple`](#allowmultiple) option).
109
+
-->
110
+
111
+
## Difference from `react-css-modules`
31
112
32
113
[`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` 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?](https://github.com/gajus/react-css-modules#whats-the-problem)). However, this approach has a measurable performance penalty (see [Performance](#performance)).
0 commit comments