Skip to content

Commit f96137c

Browse files
Barthélémy Ledouxsapegin
Barthélémy Ledoux
and
sapegin
authored
New: Add hot module reloading for theme and styles (styleguidist#1489)
* make theme hmr loadable * try making a theme hmr tool * add an example for it * add styles in the mix * fix example * fix typings * fix modulenamemapper fo jest tests * update snapshots * Add tests for the new behavior * prevent eslint from being mean to jest mock * remove rsg styles type * reorder imports * make better tests * make example filenames more explicit * remove eslint exception in example * fix webpack and add comments * update snapshots * add tests for make webpack config * augment coverage over make-webpack-config * remove useless ependency * document styles and themes hmr * fix typings * remove eslintrc changes * fix resolving of path from configDir * update docs and example * remove compile change * make better style file path * cookbook clarification * fix typings * fix typo in docs Co-Authored-By: Artem Sapegin <[email protected]> * Update case in the note docs Co-Authored-By: Artem Sapegin <[email protected]> * remove added chevrons in cookbook * update examples package and lock * remove modifications from webpack config * clean eslint changes * simplify themed example * fix redme for left button * update themed * improve types * use the styleguide-loader instead * remove all chanegs from make webpack config * make the HMR of theme work * optimize performance when not using style files * rollback unwanted changes to eslint * update whitespace * replace tabs with spaces * fix es5 export of styles and themes * update createssheet tests * remove unwanted changes * fix optimization * add various comments * add tests on styleguide-loader * more code coverage * replace RE by regExp in tests Co-Authored-By: Artem Sapegin <[email protected]> * complete the test clarification * remove custom state documentation * move all changes to styleguide-loader * avoid compiling test files * add comments regarding optimization * fix tests and styleguide loader * can't deal with default this way... * resolve es6 in loader side * ue has-sum intead of custom md5 * better case conventions for constants * rename resolve esmodule * fix typings * rename es6 test file * use destructured theme and styles * fix test name * fix types * remove hmrStyles * update comments of styleguide-loader * add comments and test * update comments Co-authored-by: Artem Sapegin <[email protected]>
1 parent b1d7d2f commit f96137c

35 files changed

+9628
-89
lines changed

‎docs/Configuration.md

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -600,11 +600,11 @@ Folder for static HTML style guide generated with `styleguidist build` command.
600600

601601
#### `styles`
602602

603-
Type: `Object` or `Function`, optional
603+
Type: `Object`, `String` or `Function`, optional
604604

605-
Customize styles of any Styleguidist’s component.
605+
Customize styles of any Styleguidist’s component using an object, a function returning said object or a file path to a file exporting said styles.
606606

607-
See example in the [cookbook](Cookbook.md#how-to-change-styles-of-a-style-guide).
607+
See examples in the [cookbook](Cookbook.md#how-to-change-styles-of-a-style-guide).
608608

609609
> **Note:** Using a function allows access to theme variables as seen in the example below. See available [theme variables](https://github.com/styleguidist/react-styleguidist/blob/master/src/client/styles/theme.ts). The returned object folows the same format as when configured as a litteral.
610610
@@ -623,6 +623,8 @@ module.exports = {
623623
}
624624
```
625625

626+
**Note:** If using a file path, it has to be absolute or relative to the config file.
627+
626628
#### `template`
627629

628630
Type: `Object` or `Function`, optional.
@@ -643,16 +645,18 @@ A function that returns an HTML string, see [mini-html-webpack-plugin docs](http
643645

644646
#### `theme`
645647

646-
Type: `object`, optional
648+
Type: `Object` or `String`, optional
647649

648-
Customize style guide UI fonts, colors, etc.
650+
Customize style guide UI fonts, colors, etc. using a theme object or the path to a file exporting such object.
649651

650-
See example in the [cookbook](Cookbook.md#how-to-change-styles-of-a-style-guide).
652+
The path is relative to the config file or absolute.
651653

652-
> **Note:** See available [theme variables](https://github.com/styleguidist/react-styleguidist/blob/master/src/client/styles/theme.ts).
654+
See examples in the [cookbook](Cookbook.md#how-to-change-styles-of-a-style-guide).
653655

656+
> **Note:** See available [theme variables](https://github.com/styleguidist/react-styleguidist/blob/master/src/client/styles/theme.ts).
657+
>
654658
> **Note:** Styles use [JSS](https://github.com/cssinjs/jss/blob/master/docs/jss-syntax.md) with these plugins: [jss-plugin-isolate](https://github.com/cssinjs/jss/tree/master/packages/jss-plugin-isolate), [jss-plugin-nested](https://github.com/cssinjs/jss/tree/master/packages/jss-plugin-nested), [jss-plugin-camel-case](https://github.com/cssinjs/jss/tree/master/packages/jss-plugin-camel-case), [jss-plugin-default-unit](https://github.com/cssinjs/jss/tree/master/packages/jss-plugin-default-unit), [jss-plugin-compose](https://github.com/cssinjs/jss/tree/master/packages/jss-plugin-compose) and [jss-plugin-global](https://github.com/cssinjs/jss/tree/master/packages/jss-plugin-global).
655-
659+
>
656660
> **Note:** Use [React Developer Tools](https://github.com/facebook/react) to find component and style names. For example a component `<LogoRenderer><h1 className="rsg--logo-53">` corresponds to an example above.
657661
658662
#### `title`
@@ -825,11 +829,11 @@ module.exports = {
825829
```
826830

827831
> **Warning:** This option disables config load from `webpack.config.js`, load your config [manually](Webpack.md#reusing-your-projects-webpack-config).
828-
832+
>
829833
> **Note:** `entry`, `externals`, `output`, `watch`, and `stats` options will be ignored. For production builds, `devtool` will also be ignored.
830-
834+
>
831835
> **Note:** `CommonsChunkPlugins`, `HtmlWebpackPlugin`, `MiniHtmlWebpackPlugin`, `UglifyJsPlugin`, `TerserPlugin`, `HotModuleReplacementPlugin` plugins will be ignored because Styleguidist already includes them or they may break Styleguidist.
832-
836+
>
833837
> **Note:** Run style guide in verbose mode to see the actual webpack config used by Styleguidist: `npx styleguidist server --verbose`.
834838
835839
See [Configuring webpack](Webpack.md) for examples.

‎docs/Cookbook.md

Lines changed: 57 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -265,7 +265,56 @@ module.exports = {
265265
266266
> **Note:** Use [React Developer Tools](https://github.com/facebook/react) to find component and style names. For example a component `<LogoRenderer><h1 className="rsg--logo-53">` corresponds to an example above.
267267
268-
> **Note:** Use a function instead of an object for [styles](Configuration.md#styles) to access all heme variables in your custom styles.
268+
> **Note:** Use a function instead of an object for [styles](Configuration.md#styles) to access all theme variables in your custom styles.
269+
270+
You can store all styles in a separate file to allow hot module replacement (HMR). Same goes for theme variables.
271+
272+
The same example above would then translate as:
273+
274+
In `styleguide.config,js`, objects are replaced with file paths
275+
276+
```javascript
277+
module.exports = {
278+
// ...
279+
styles: './styleguide/styles.js',
280+
theme: './styleguide/themes.js'
281+
}
282+
```
283+
284+
then in `./styleguide/theme.js`
285+
286+
```javascript
287+
module.exports = {
288+
color: {
289+
link: 'firebrick',
290+
linkHover: 'salmon'
291+
},
292+
fontFamily: {
293+
base: '"Comic Sans MS", "Comic Sans", cursive'
294+
}
295+
}
296+
```
297+
298+
and in `./styleguide/styles.js`
299+
300+
```javascript
301+
module.exports = {
302+
Logo: {
303+
// We're changing the LogoRenderer component
304+
logo: {
305+
// We're changing the rsg--logo-XX class name inside the component
306+
animation: 'blink ease-in-out 300ms infinite'
307+
},
308+
'@keyframes blink': {
309+
to: { opacity: 0 }
310+
}
311+
}
312+
}
313+
```
314+
315+
Each modification of `theme.js` or `styles.js` will trigger a hot module replacement, updating the styleguide in the browser.
316+
317+
Check out the [themed example](https://github.com/styleguidist/react-styleguidist/tree/master/examples/themed) on the github repo to learn more and try it out.
269318

270319
```javascript
271320
module.exports = {
@@ -406,16 +455,16 @@ module.exports = {
406455

407456
## How to debug my components and examples?
408457

409-
1. Open your browser’s developer tools
410-
2. Write `debugger;` statement wherever you want: in a component source, a Markdown example or even in an editor in a browser.
458+
1. Open your browser’s developer tools
459+
2. Write `debugger;` statement wherever you want: in a component source, a Markdown example or even in an editor in a browser.
411460

412461
![](https://d3vv6lp55qjaqc.cloudfront.net/items/3i3E3j2h3t1315141k0o/debugging.png)
413462

414463
## How to debug the exceptions thrown from my components?
415464

416-
1. Put `debugger;` statement at the beginning of your code.
417-
2. Press the ![Debugger](https://d3vv6lp55qjaqc.cloudfront.net/items/2h2q3N123N3G3R252o41/debugger.png) button in your browser’s developer tools.
418-
3. Press the ![Continue](https://d3vv6lp55qjaqc.cloudfront.net/items/3b3c1P3g3O1h3q111I2l/continue.png) button and the debugger will stop execution at the next exception.
465+
1. Put `debugger;` statement at the beginning of your code.
466+
2. Press the ![Debugger](https://d3vv6lp55qjaqc.cloudfront.net/items/2h2q3N123N3G3R252o41/debugger.png) button in your browser’s developer tools.
467+
3. Press the ![Continue](https://d3vv6lp55qjaqc.cloudfront.net/items/3b3c1P3g3O1h3q111I2l/continue.png) button and the debugger will stop execution at the next exception.
419468

420469
## How to use the production or development build of React?
421470

@@ -461,9 +510,9 @@ devServer: {
461510

462511
Two options:
463512

464-
1. Put a `favicon.ico` file into the root folder of your site.
513+
1. Put a `favicon.ico` file into the root folder of your site.
465514

466-
2. Use [template](Configuration.md#template) option:
515+
2. Use [template](Configuration.md#template) option:
467516

468517
```javascript
469518
module.exports = {

‎examples/themed/Readme.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# React Styleguidist themed example style guide
2+
3+
How to start locally:
4+
5+
```
6+
git clone https://github.com/styleguidist/react-styleguidist.git
7+
cd react-styleguidist/examples/themed
8+
npm install
9+
npx styleguidist server
10+
```
11+
12+
Then open [http://localhost:6060](http://localhost:6060) in your browser.

‎examples/themed/babel.config.js

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
module.exports = {
2+
presets: [
3+
[
4+
'@babel/env',
5+
{
6+
modules: false,
7+
useBuiltIns: 'usage',
8+
corejs: 3,
9+
},
10+
],
11+
'@babel/react',
12+
],
13+
plugins: ['@babel/plugin-proposal-class-properties'],
14+
};

0 commit comments

Comments
 (0)