React Styleguidist

Configuring webpack

Styleguidist uses webpack under the hood and it needs to know how to load your project’s files.

Webpack is required to run Styleguidist but your project doesn’t have to use it.

See cookbook for more examples.

Reusing your project’s webpack config

By default Styleguidist will try to find webpack.config.js in your project’s root directory and use it.

If your webpack config is located somewhere else, you need to load it manually:

module.exports = {
  webpackConfig: require('./configs/webpack.js')
};

Or if you want to merge it with other options:

module.exports = {
  webpackConfig: Object.assign({},
    require('./configs/webpack.js'),
    {
      /* Custom config options */
    }
  )
};

entry, externals, output, watch, and stats options will be ignored. For production builds, devtool will also be ignored.

CommonsChunkPlugins, HtmlWebpackPlugin, UglifyJsPlugin, HotModuleReplacementPlugin plugins will be ignored because Styleguidist already includes them or they may break Styleguidist.

If your loaders don’t work with Styleguidist try to make include and exclude absolute paths.

Babelified webpack configs (like webpack.config.babel.js) are not supported. We recommend to convert your config to native Node — Node 6 supports many ES6 features.

Use webpack-merge for easier config merging.

Custom webpack config

Add a webpackConfig section to your styleguide.config.js:

module.exports = {
  webpackConfig: {
    module: {
      rules: [
        // Babel loader, will use your project’s .babelrc
        {
          test: /\.jsx?$/,
          exclude: /node_modules/,
          loader: 'babel-loader'
        },
        // Other loaders that are needed for your components
        {
          test: /\.css$/,
          loader: 'style-loader!css-loader?modules'
        }
      ]
    }
  }
};

This option disables config load from webpack.config.js, see above how to load your config manually.

entry, externals, output, watch, and stats options will be ignored. For production builds, devtool will also be ignored.

CommonsChunkPlugins, HtmlWebpackPlugin, UglifyJsPlugin, HotModuleReplacementPlugin plugins will be ignored because Styleguidist already includes them or they may break Styleguidist.

Create React App

Create React App is supported out of the box, you don’t even need to create a style guide config if your components could be found using a default glob pattern, src/components/**/*.{js,jsx}.

Create React App, TypeScript

If you're using Create React App and Typescript, you need to:

  • Install react-docgen-typescript
  • Create a styleguide.config.js, see this guide
  • Add a components, webpackConfig and propsParser section to your styleguide.config.js:
module.exports = {
  components: 'src/components/**/*.{ts,tsx}',
  propsParser: require('react-docgen-typescript').parse,
  webpackConfig: require('react-scripts-ts/config/webpack.config.dev.js')
}

Non-webpack projects

If your project doesn’t use webpack you still need loaders for your files. You can use webpack-blocks.

npm install --save-dev webpack-blocks

Then add a webpackConfig section to your styleguide.config.js:

const { createConfig, babel, postcss } = require('webpack-blocks');
module.exports = {
	webpackConfig: createConfig([
		babel(),
		postcss()
	])
};

.babelrc and postcss.config.js files will be taken into account if you have them.

When nothing else works

In very rare cases, like using legacy or third-party libraries, you may need to change webpack options that Styleguidist doesn’t allow you to change via webpackConfig options. In this case you can use dangerouslyUpdateWebpackConfig option.

You may easily break Styleguidist using this options, use it at your own risk.