This text explains how one can combine Storybook and Chromatic to scale your React utility’s part library and profit from clear documentation, visible regression testing and workforce effectivity.

Desk of Contents

Why Use Storybook?

Storybook is a useful software for engineers, product house owners and stakeholders alike. Storybook permits frontend engineering groups to construct part libraries to facilitate collaboration and stop the event of elements from being blocked by extra vital challenge structure selections.

It acts as a standalone utility inside your extra in depth challenge that may doc elements and their variations. Storybook comes full of a ton of options which could be personalized and configured to your liking. Beneath are a number of the options I take advantage of on on a regular basis tasks:

  • internet accessibility audits
  • unit, interplay and snapshot testing
  • doc part performance for engineers and stakeholders
  • straightforward publishing and internet hosting
  • integration with Chromatic for visible regression testing (VRT)

This text explores putting in and configuring Storybook in a pattern Create React App challenge, putting in add-ons, writing tales, producing automated documentation and publishing your Storybook to the Internet.

Setting Up and Configuring Storybook

Let’s first have a look at set up.

Putting in Storybook

Storybook was developed to suit right into a plethora of various challenge sorts. The simplest solution to get began with Storybook is to put in it right into a pre-existing utility and run a easy command on the root of your challenge:

npx storybook@newest init

The above command will have a look at your challenge dependencies and decide probably the most acceptable solution to set up Storybook.

In the event you need assistance figuring out whether or not your challenge would assist Storybook, learn by the Frameworks page within the documentation.

Word: you’ll be able to set up Storybook manually, however this usually leads to errors and mismanaged dependencies, which might trigger issues.

Configuring Storybook

One of many extra advanced facets of Storybook is configuring it to align with applied sciences current in your utility. Additional customization shall be required to make sure Storybook behaves in a fashion aligned along with your utility’s expertise stack.

Configuring Storybook is primarily performed by the foremost.js file. You may specify every little thing right here — from how documentation is offered, to extending Storybook’s UI with add-ons. You may even lengthen Webpack.

Storybook helps TypeScript out of the field, however you need to arrange your CSS structure. Many flavors of CSS are supported. You will discover extra info within the Styling and CSS documentation.

Let’s spin up a Create React App occasion:

npx create-react-app my-scalable-component-library

The above command will bootstrap a fundamental React utility. We’ll be utilizing Create React App for this text, although different frameworks are additionally supported. Let’s ensure your utility is working accurately by operating npm run begin. It is best to see one thing much like what’s pictured under.

A screenshot of Create React Apps initial screen

Let’s set up Storybook subsequent. Run the next line within the root of your utility:

npx storybook@newest init

The script will do a little bit of pondering after which immediate you to substantiate just a few particulars. Storybook is sensible sufficient to detect that we’re utilizing Create React App (CRA), and it’ll probably have to replace just a few dependencies to work seamlessly along with your challenge. Hit Y while you see the immediate pictured under.

A screenshot of the output of running Storybook for the first time

If all goes in accordance with plan, Storybook will launch in your browser, and also you’ll see what’s pictured under.

A screenshot of a successfully installed Storybook in the browser

At this level, it’s value taking a look at what’s modified in our challenge. Storybook added a .storybook folder the place your configuration recordsdata stay. You’ll additionally discover a tales folder added to the src listing. There are usually three associated recordsdata for every “story”. We’ll uncover that in additional element a bit later.

Each the package deal.json and package-lock.json have been up to date. Updates to those recordsdata pertain primarily to dependencies, however package deal.json additionally has two new scripts:

"storybook": "storybook dev -p 6006",
"build-storybook": "storybook construct"

Run npm run storybook to spin up a dev atmosphere and npm run build-storybook while you’re able to publish your first Storybook.

Let’s run npm run build-storybook. The output is a folder known as storybook-static: this can be a “printed” Storybook that may be made publicly accessible.

At this level, Storybook and CRA are solely arrange. You could need to add the storybook-static folder to your .gitignore should you don’t plan to trace the static recordsdata.

It’s additionally value noting {that a} handful of elements have been added to your listing. You may take away them if want be. Nevertheless, I like to recommend maintaining them for reference, if for nothing else. Earlier than we transfer on, let’s briefly check out foremost.js:

const config = {
  tales: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
  addons: [
  framework: {
    identify: "@storybook/react-webpack5",
    choices: {},
  docs: {
    autodocs: "tag",
  statistics: ["../public"],
export default config;

There are just a few important components to this file. Firstly, the tales key tells the Storybook the place to search for part tales. As you replace your file/folder structure in CRA, replace these paths to keep away from shedding your tales in Storybook.

framework is usually totally different for every challenge sort. docs tells Storybook to doc elements routinely.

I’d extremely advocate reading the Configure page within the Storybook docs for extra details about what could be dealt with by foremost.js.

Deciding on Storybook Add-ons

You may consider Storybook add-ons as “plugins”. They’re pre-written packages that reach the core Storybook APIs and carry out duties like integrating JS/CSS frameworks or enhancing the default conduct of Storybook.

What add-ons you put in will rely in your challenge and your workforce’s objectives. There are successfully two forms of add-ons: UI-based and preset-based. “UI-based” add-ons customise the practical look of Storybook. “Preset-based” add-ons permit you to combine with different applied sciences like TypeScript or Tailwind. You will discover a set of all add-ons on the Integrations web page.

Word: some add-ons are maintained by the Storybook workforce, whereas others are community-driven. Group-driven add-ons could yield sudden outcomes or is probably not suitable with the most recent model of Storybook.

Earlier than you go on the hunt for a set of add-ons you’re feeling shall be finest to combine, ensure you check out what Storybook installs by default:

addons: [
  1. @storybook/addon-links permits you to hyperlink Tales to construct prototypes.
  2. @storybook/addon-essentials embrace all add-ons positioned right here:
  3. @storybook/preset-create-react-app is a preset-based add-on that enhances the combination with CRA.
  4. @storybook/addon-onboarding supplies a guided tour of Storybook options.
  5. @storybook/addon-interactions means that you can debug the interplay state of your elements. In the event you’re , you’ll be able to read more about Interaction tests.

Let’s say you need to add one other add-on to your configuration. Let’s set up the Accessibility add-on:

npm set up @Storybook/addon-a11y

Subsequent, we have to inform Storybook to initialize the add-on. This may be performed by including the add-on to the addons key in foremost.js:

addons: [

Save foremost.js, after which let’s boot up Storybook once more by operating npm run storybook.

A screenshot of the newly added Accessibility panel

You may see now that the “Accessibility” tab has been added to all story situations and is already flagging issues with a11y in our elements. “UI-based” add-ons solely require a bit configuration. “Preset-based” could be extra advanced. The explanation for that is that “preset-based” add-ons typically want additional configuration, reminiscent of:

  • inserting configuration recordsdata on the root of your challenge
  • configuring choices / Webpack configurations that should align along with your CRA utility settings

This may trigger numerous friction, and remediation can rely on the framework of alternative. Use warning when extending Storybook with “preset-based” add-ons and guarantee parity along with your utility.

Writing and Documenting Element Tales

It’s now time to write down tales. A narrative in Storybook is often tied to a part and its variations. Tales are extremely dynamic recordsdata written in React, Markdown, or a mix of each applied sciences. Tales are handed parameters that align with props the React part accepts.

These props could be configured to output variations of every part. This enables engineers to work together with prop values throughout the Storybook UI. Let’s assessment our Button story that was added by our bootstrapping of Storybook:

import { Button } from './Button';

export default {
  title: 'Instance/Button',
  part: Button,
  parameters: {
    format: 'centered',
  tags: ['autodocs'],
  argTypes: {
    background-color: { management: 'shade' },

export const Main = {
  args: {
    major: true,
    label: 'Button',

export const Secondary = {
  args: {
    label: 'Button',

export const Massive = {
  args: {
    measurement: 'massive',
    label: 'Button',

export const Small = {
  args: {
    measurement: 'small',
    label: 'Button',

The above illustrates the format you’ll be able to observe when making a Story. There should all the time be a default export. That is the principle part. It’s the place important settings are configured. Most of them are self-explanatory. Nevertheless, I wish to name out the next:

  • Parameters are a set of static, named metadata a few story, usually used to regulate the conduct of Storybook options and add-ons.
  • Tags will auto-generate documentation for every part story. Learn extra about AutoDocs.
  • argTypes specify the conduct of args or annotate args. Read more about archetypes.

Any named export after the preliminary default export is a variation. Every variation is an object with an args key. args on this context ought to align with the props handed to your part. Every variation shall be output in Storybook underneath the Button part, and you’ll work together with them as wanted.

Understanding Decorators goes a great distance should you plan on constructing extra advanced tales. A decorator supplies a solution to wrap tales in additional context and performance. Tales could be handed to a decorator by setting the decorator key within the story parameters:

decorators: [
    (Story) => (
      <div style={{ margin: '3em' }}>
        <Story />

Within the instance above, we add a <div> that wraps our part, and we assign it 3em of margin.

Tales can even devour elements from different Tales. Simply be aware that this may depend on how your part renders and the way a lot element you propose on including to your utility general.

Within the Storybook docs, you’ll be able to examine Sub Components in detail.

Writing a Story for our utility

Let’s put this all to the take a look at. We’re going so as to add a part to our utility known as Footer. This can require three recordsdata:

  • Footer.jsx
  • Footer.tales.js
  • footer.css

Create these recordsdata within the src/tales folder. Our Footer.jsx goes to be easy:

import React from 'react';
import PropTypes from 'prop-types';

export const Footer = ({ siteOwner, showCopyRight }) => (
    <div className="footer">
      {showCopyRight && (
            <span position="img" aria-label="copy">©️</span> 2018 {siteOwner}.

Footer.propTypes = {
  siteOwner: PropTypes.string.isRequired,
  showCopyRight: PropTypes.bool,

Footer.defaultProps = {
  showCopyRight: true,

It takes two props: siteOwner and showCopyRight. Subsequent up, let’s write a narrative for the Footer:

import { Footer } from './Footer';

export default {
  title: 'Instance/Footer',
  part: Footer,
  tags: ['autodocs'],
  parameters: {
    format: 'fullscreen',

export const WithSiteOwner = {
  args: {
    siteOwner: 'Jane Doe',
    showCopyRight: true,

export const WithOutCopyRight = {
  args: {
    siteOwner: 'Jane Doe',
    showCopyRight: false,

This can be a comparatively contrived instance, however it illustrates how straightforward it’s so as to add a narrative. Add the above to Footer.tales.js. The outcome shall be an auto-documented, multi-variant story that permits customers to work together with the part’s props.

A screenshot of the Footer story recently added to Storybook

Strive updating the siteOwner worth instantly within the story controls. If you wish to fashion the Footer, import footer.css into Footer.jsx and reference the category names. In the event you’re all for seeing how the part behaves in your React utility, import it:

import { Footer } from './tales/Footer';
<Footer siteOwner='Daine Mawer' showCopyRight />

Good! You’ve simply created your part and a corresponding story! Subsequent, we’ll focus on publishing your storybook on the Internet.

Publishing Your Storybook

Engineers can simply view and develop domestically on Storybook, because the configuration is tracked by your most well-liked model management system. Nevertheless, a URL to entry the printed Storybook can be much more manageable for non-technical stakeholders.

While you run a manufacturing construct of Storybook, its output is a set of static recordsdata which are outputted right into a construct folder. Fortunately, the Storybook workforce has made this comparatively straightforward to realize. All you might want to do is run this:

npm run build-storybook

The construct will terminate if it comes throughout any construct errors, so there’s no approach of publishing a damaged Storybook. Now that now we have a manufacturing construct, we’d like someplace to host it.

There are a number of methods to do that: GitHub Pages, Netlify, and AWS S3. A few of these choices require extra configuration than others.

In the event you don’t plan on organising Chromatic (advisable), I like to recommend operating with GitHub Pages, as you’ll be able to add a GitHub Action to make brief work of the configuration and setup.

Setting Up Chromatic for VRT

Chromatic is a strong software that lives alongside Storybook. The Storybook workforce maintains Chromatic, so integrating the software into your pre-existing utility and CI requires minimal effort.

By integrating Chromatic, you’ll be able to make sure that visible regressions, even interplay bugs, don’t make it to your manufacturing atmosphere. The appliance permits for seamless collaboration inside groups and goes a protracted solution to making certain bugs are caught early and infrequently.

What’s extra, Chromatic is free — with limitations, after all.

Let’s say we need to combine Chromatic with our printed Storybook. Join a Chromatic account and seize a Undertaking Token. Subsequent, you’ll want to put in the Chromatic npm package deal into your challenge:

npm set up --save-dev chromatic

Then add a chromatic script to your package deal.json:

"scripts": {
    "chromatic": "chromatic"

You’ll then want to make sure that you will have a .env file with the next atmosphere variable outlined: CHROMATIC_PROJECT_TOKEN. You may add the Undertaking Token out of your Chromatic account as the worth.

Run npm run chromatic. This can publish your Storybook to your Chromatic challenge. You may then entry a powerful UI to assessment elements and their adjustments. The issue with this setup is that you just’ll have to run Chromatic every time you modify elements.

This can be okay for smaller tasks, however committing adjustments to your utility and having a CI pipeline deal with this difficult work is much better. Chromatic CI integrates instantly into pull requests.

In the event you’re utilizing GitHub, you’ll be able to rapidly rise up and operating with GitHub Actions by including a workflows folder to your .github listing. Observe the steps in Chromatic Docs outlined at Automate Chromatic with GitHub Actions to rise up and operating.

You’ve got now printed a part library that runs UI Assessments and Opinions every time you commit adjustments to your elements.

Conclusion and Takeaways

Storybook and Chromatic instruments will empower your workforce to ship higher-quality code. Use Storybook to automate and iterate in your shared part libraries.

Above all else, these two instruments will guarantee your engineering workforce can develop in confidence, ship options and bug fixes extra effectively and be sure that your product is all the time well-documented, scalable and extensible.