Configuring Storybook: 6 Tips You Can’t Miss

How to configure your Storybook to be integrated with a current project

Storybook is an open-source tool for UI development with a variety of addons to display your UI components in an interactive and detailed way.

Here is how storybook looks

I am excited to share my experiences on how to configure your Storybook to integrate it into your current project. This article will be focused on the problems I’ve encountered and how I solved them.

To begin with, I recommend that you read the information on the Storybook configuration from the official website to have a basic understanding.

Configuration files

The configuration files are located in your project root fold .storybook, and the most important ones are main.js preview.js manager.js The main config file is main.js, there is a chance that you don’t need to config other files. This article will put more value on main.js and preview.js

main.js

As it is clearly stated in Storybook documentation:

The main.js configuration file is a preset and as such has a powerful interface, but the key fields within it are:

1. stories- an array of globs that indicates the location of your story files, relative to main.js.
2. addons - a list of the addons you are using.
3. webpackFinal - custom webpack configuration.
4. babel - custom babel configuration.

module.exports = {
// The location of your stories
  stories: ['../src/**/*.stories.@(js|mdx)'],
// addons added to your storybook
  addons: ['@storybook/addon-essentials'],
// custom babel config  
  babel: async (options) => ({
      ...options,
      // any extra options you want to set
  }),
//  custom webpack config
webpackFinal: async (config, { configType }) => {
    // `configType` has a value of 'DEVELOPMENT' or 'PRODUCTION'
    // You can change the configuration based on that.
    // 'PRODUCTION' is used when building the static version of storybook.

    // Make whatever fine-grained changes you need
    config.module.rules.push({
      test: /\.scss$/,
      use: ['style-loader', 'css-loader', 'sass-loader'],
      include: path.resolve(__dirname, '../'),
    });

    // Return the altered config
    return config;
  }
}

Tip 1: The Storybook has its default webpack configuration, when trying to import your current webpack config or add your own rules, DO use push to add your rules to the rules array, or mutable the config object.

config.module.rules.push({
      test: /\.scss$/,
      use: ['style-loader', 'css-loader', 'sass-loader'],
      include: path.resolve(__dirname, '../'),
    });

Config the necessary alias that already applies to your current project.

config.resolve.alias = {
    ...config.resolve.alias,
    "ui-components": path.resolve(__dirname, "../src")
};

Tip 2: To check the final webpack config, you can run yarn storybook --debug-webpack to print the config in your terminal or you can add console.log(config.module.rules) inside webpackFinal function, and run yarn storybook to print only part of the final webpack config.

Tip 3: Since version 6.0, Storybook add essential addons by default, including Docs, Controls, Actions, Viewport, Backgrounds, Toolbars. You can check the release note here.

All you need is to add essential addons in config.

addons: ['@storybook/addon-essentials']

With docs and control addons, Arg Table/Props Table can be added

preview.js

To control the way stories are rendered and add global decorators and parameters, create a .storybook/preview.js file. This is loaded in the Canvas tab, the “preview” iframe that renders your components in isolation. Use preview.js for global code (such as CSS imports or JavaScript mocks) that applies to all stories.

The preview.js file can be an ES module and export the following keys:

decorators - an array of global decorators

parameters - an object of global parameters

globalTypes - definition of globalTypes

If you’re looking to change how your stories are ordered, read about sorting stories.

Tip 4: preview.js is the file where you can also import the global css/sass, so it will apply the styles to your components.

import “../src/styles/theme.css”;

Tip 5: If you have a top wrapper with a specific class name which has styles, you should add the same wrapper through decorator.

import { addDecorator } from "@storybook/react";
// For each story, the parent element will be div with class name "platform"
addDecorator(story => <div className="platform">{story()}</div>);

Tip 6: Any other global config or javascript mocks (formatters etc.) should be added in preview.js

import { addDecorator } from "@storybook/react";
import { withI18n } from "storybook-addon-i18n";
addDecorator(withI18n);

manager.js

The manager.js is to control the behaviour of Storybook’s UI. You can set UI options and configure Storybook’s theme. It is optional and no need to add if your project doesn’t have the requirement for customised Storybook UI/theme.

To conclude

Since Storybook 6.0, the Storybook team makes it easier to configure, even though some of the config is missing or not written in a very detailed way in the documentation. But you can always ask for help by starting an issue in Github. Also, you are very welcome to become an open source contributor — learn how you can contribute here.