New: Add hot module reloading for theme and styles (#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 <artem@sapegin.ru> * Update case in the note docs Co-Authored-By: Artem Sapegin <artem@sapegin.ru> * 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 <artem@sapegin.ru> * 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 <artem@sapegin.ru>
styleguidist · Jan 13, 2020 · f96137c · f96137c
1 parent b1d7d2f
commit f96137c
Show file tree

Hide file tree

Showing 35 changed files with 9,628 additions and 89 deletions.
diff --git a/docs/Configuration.md b/docs/Configuration.md
@@ -600,11 +600,11 @@ Folder for static HTML style guide generated with `styleguidist build` command.
 
 #### `styles`
 
-Type: `Object` or `Function`, optional
+Type: `Object`, `String` or `Function`, optional
 
-Customize styles of any Styleguidist’s component.
+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.
 
-See example in the [cookbook](Cookbook.md#how-to-change-styles-of-a-style-guide).
+See examples in the [cookbook](Cookbook.md#how-to-change-styles-of-a-style-guide).
 
 > **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.
 
@@ -623,6 +623,8 @@ module.exports = {
 }
 ```
 
+**Note:** If using a file path, it has to be absolute or relative to the config file.
+
 #### `template`
 
 Type: `Object` or `Function`, optional.
@@ -643,16 +645,18 @@ A function that returns an HTML string, see [mini-html-webpack-plugin docs](http
 
 #### `theme`
 
-Type: `object`, optional
+Type: `Object` or `String`, optional
 
-Customize style guide UI fonts, colors, etc.
+Customize style guide UI fonts, colors, etc. using a theme object or the path to a file exporting such object.
 
-See example in the [cookbook](Cookbook.md#how-to-change-styles-of-a-style-guide).
+The path is relative to the config file or absolute.
 
-> **Note:** See available [theme variables](https://github.com/styleguidist/react-styleguidist/blob/master/src/client/styles/theme.ts).
+See examples in the [cookbook](Cookbook.md#how-to-change-styles-of-a-style-guide).
 
+> **Note:** See available [theme variables](https://github.com/styleguidist/react-styleguidist/blob/master/src/client/styles/theme.ts).
+>
 > **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).
-
+>
 > **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.
 
 #### `title`
@@ -825,11 +829,11 @@ module.exports = {
 ```
 
 > **Warning:** This option disables config load from `webpack.config.js`, load your config [manually](Webpack.md#reusing-your-projects-webpack-config).
-
+>
 > **Note:** `entry`, `externals`, `output`, `watch`, and `stats` options will be ignored. For production builds, `devtool` will also be ignored.
-
+>
 > **Note:** `CommonsChunkPlugins`, `HtmlWebpackPlugin`, `MiniHtmlWebpackPlugin`, `UglifyJsPlugin`, `TerserPlugin`, `HotModuleReplacementPlugin` plugins will be ignored because Styleguidist already includes them or they may break Styleguidist.
-
+>
 > **Note:** Run style guide in verbose mode to see the actual webpack config used by Styleguidist: `npx styleguidist server --verbose`.
 
 See [Configuring webpack](Webpack.md) for examples.
diff --git a/docs/Cookbook.md b/docs/Cookbook.md
@@ -265,7 +265,56 @@ module.exports = {
 
 > **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.
 
-> **Note:** Use a function instead of an object for [styles](Configuration.md#styles) to access all heme variables in your custom styles.
+> **Note:** Use a function instead of an object for [styles](Configuration.md#styles) to access all theme variables in your custom styles.
+
+You can store all styles in a separate file to allow hot module replacement (HMR). Same goes for theme variables.
+
+The same example above would then translate as:
+
+In `styleguide.config,js`, objects are replaced with file paths
+
+```javascript
+module.exports = {
+  // ...
+  styles: './styleguide/styles.js',
+  theme: './styleguide/themes.js'
+}
+```
+
+then in `./styleguide/theme.js`
+
+```javascript
+module.exports = {
+  color: {
+    link: 'firebrick',
+    linkHover: 'salmon'
+  },
+  fontFamily: {
+    base: '"Comic Sans MS", "Comic Sans", cursive'
+  }
+}
+```
+
+and in `./styleguide/styles.js`
+
+```javascript
+module.exports = {
+  Logo: {
+    // We're changing the LogoRenderer component
+    logo: {
+      // We're changing the rsg--logo-XX class name inside the component
+      animation: 'blink ease-in-out 300ms infinite'
+    },
+    '@keyframes blink': {
+      to: { opacity: 0 }
+    }
+  }
+}
+```
+
+Each modification of `theme.js` or `styles.js` will trigger a hot module replacement, updating the styleguide in the browser.
+
+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.
 
 ```javascript
 module.exports = {
@@ -406,16 +455,16 @@ module.exports = {
 
 ## How to debug my components and examples?
 
-1.  Open your browser’s developer tools
-2.  Write `debugger;` statement wherever you want: in a component source, a Markdown example or even in an editor in a browser.
+1. Open your browser’s developer tools
+2. Write `debugger;` statement wherever you want: in a component source, a Markdown example or even in an editor in a browser.
 
 ![](https://d3vv6lp55qjaqc.cloudfront.net/items/3i3E3j2h3t1315141k0o/debugging.png)
 
 ## How to debug the exceptions thrown from my components?
 
-1.  Put `debugger;` statement at the beginning of your code.
-2.  Press the ![Debugger](https://d3vv6lp55qjaqc.cloudfront.net/items/2h2q3N123N3G3R252o41/debugger.png) button in your browser’s developer tools.
-3.  Press the ![Continue](https://d3vv6lp55qjaqc.cloudfront.net/items/3b3c1P3g3O1h3q111I2l/continue.png) button and the debugger will stop execution at the next exception.
+1. Put `debugger;` statement at the beginning of your code.
+2. Press the ![Debugger](https://d3vv6lp55qjaqc.cloudfront.net/items/2h2q3N123N3G3R252o41/debugger.png) button in your browser’s developer tools.
+3. Press the ![Continue](https://d3vv6lp55qjaqc.cloudfront.net/items/3b3c1P3g3O1h3q111I2l/continue.png) button and the debugger will stop execution at the next exception.
 
 ## How to use the production or development build of React?
 
@@ -461,9 +510,9 @@ devServer: {
 
 Two options:
 
-1.  Put a `favicon.ico` file into the root folder of your site.
+1. Put a `favicon.ico` file into the root folder of your site.
 
-2.  Use [template](Configuration.md#template) option:
+2. Use [template](Configuration.md#template) option:
 
 ```javascript
 module.exports = {

diff --git a/examples/themed/Readme.md b/examples/themed/Readme.md
@@ -0,0 +1,12 @@
+# React Styleguidist themed example style guide
+
+How to start locally:
+
+```
+git clone https://github.com/styleguidist/react-styleguidist.git
+cd react-styleguidist/examples/themed
+npm install
+npx styleguidist server
+```
+
+Then open [http://localhost:6060](http://localhost:6060) in your browser.
diff --git a/examples/themed/babel.config.js b/examples/themed/babel.config.js
@@ -0,0 +1,14 @@
+module.exports = {
+	presets: [
+		[
+			'@babel/env',
+			{
+				modules: false,
+				useBuiltIns: 'usage',
+				corejs: 3,
+			},
+		],
+		'@babel/react',
+	],
+	plugins: ['@babel/plugin-proposal-class-properties'],
+};