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.

note

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, merge it with other options:

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

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

caution

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

tip

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

note

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.

tip

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 babel.config.js
{
test: /\.jsx?$/,
exclude: /node_modules/,
loader: 'babel-loader'
},
// Other loaders that are needed for your components
{
test: /\.css$/,
use: ['style-loader', 'css-loader']
}
]
}
}
}
caution

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

caution

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

caution

CommonsChunkPlugins, HtmlWebpackPlugin, MiniHtmlWebpackPlugin, UglifyJsPlugin, TerserPlugin, 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 pattern: all files with .js or .jsx extensions inside src/components or src/Components folders.

Next.js

The Next.js framework abstracts away webpack for you, but it still uses webpack under the hood.

After configuring your webpack loaders in styleguide.config.js you will need to also configure Babel. First install all the required Babel dependencies:

npm install --save-dev babel-loader @babel/core @babel/preset-react

Next, you'll want to configure Babel to use the appropriate presets, here is an example .babelrc file:

{
"presets": ["@babel/preset-react"]
}

That's it, notice that we don't need to install webpack as it's already included by Next.js.

Non-webpack projects

To use features, not supported by browsers, like JSX, you’ll need to compile your code with Babel or another tool.

Let’s configure Styleguidist with Babel.

info

Babel is not required for Styleguidist or React, but likely you’ll want to use it to run your code.

First, install the Babel webpack loader:

npm install --save-dev babel-loader
caution

If your project doesn’t use webpack you still need to add webpack loaders for your files, otherwise Styleguidist won’t be able to load your code.

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

module.exports = {
webpackConfig: {
module: {
rules: [
{
test: /\.jsx?$/,
exclude: /node_modules/,
loader: 'babel-loader'
}
]
}
}
}

or create a webpack config, webpack.config.js:

module: {
rules: [
{
test: /\.jsx?$/,
exclude: /node_modules/,
loader: 'babel-loader'
}
]
}

If you don’t have Babel in your project, you need to install it with two presets — env and react:

npm install --save-dev @babel/core @babel/preset-env @babel/preset-react

And create a config file in your project’s root folder, babel.config.js:

module.exports = {
presets: [
[
'@babel/env',
{
modules: false,
useBuiltIns: 'usage'
}
],
'@babel/react'
]
}

We also recommend to add a browserslist config to your package.json file like this:

+ "browserslist": [
+ ">1%",
+ "last 1 version",
+ "Firefox ESR",
+ "not dead"
+ ]

This will tell Babel (and some other tools) which browsers you support, so it won’t apply unnecessary transformations, making code smaller and faster.

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.

danger

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

Edit this page