Skip to content

Commit 266606b

Browse files
committed
docs: change heading
1 parent b15942a commit 266606b

File tree

1 file changed

+83
-2
lines changed

1 file changed

+83
-2
lines changed

README.md

Lines changed: 83 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ Transforms `styleName` to `className` using compile time [CSS module](https://gi
1212

1313
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).
1414

15-
* [Background](#background)
15+
* [CSS Modules](#css-modules)
16+
* [Difference from `react-css-modules`](#difference-from-react-css-modules)
1617
* [Performance](#performance)
1718
* [How does it work?](#how-does-it-work)
1819
* [Conventions](#conventions)
@@ -27,7 +28,87 @@ In contrast to [`react-css-modules`](https://github.com/gajus/react-css-modules)
2728
* [Limitations](#limitations)
2829
* [Have a question or want to suggest an improvement?](#have-a-question-or-want-to-suggest-an-improvement)
2930

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+
import React from 'react';
39+
import styles from './table.css';
40+
41+
export default class Table extends React.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+
import React from 'react';
81+
import './table.css';
82+
83+
export default class Table extends React.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.
101+
102+
```js
103+
<div className='global-css' styleName='local-module'></div>
104+
```
105+
106+
<!--
107+
* 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`
31112

32113
[`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)).
33114

0 commit comments

Comments
 (0)