New: Add hot module reloading for theme and styles

docs/Configuration.md

@@ -610,11 +610,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.
 
@@ -633,6 +633,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.
@@ -653,16 +655,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`
@@ -824,11 +828,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.

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 = {

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.

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'],
+};