Scale Your React App with Storybook and Chromatic

This text explains learn how to combine Storybook and Chromatic to scale your React software’s part library and profit from clear documentation, visible regression testing and staff effectivity.

Why Use Storybook?

Storybook is a useful instrument for engineers, product homeowners and stakeholders alike. Storybook permits frontend engineering groups to construct part libraries to facilitate collaboration and stop the event of parts from being blocked by extra important mission structure selections.

It acts as a standalone software inside your extra intensive mission that may doc parts and their variations. Storybook comes filled with a ton of options which will be custom-made and configured to your liking. Under are among the options I exploit on on a regular basis tasks:

• internet accessibility audits
• unit, interplay and snapshot testing
• doc part performance for engineers and stakeholders
• simple 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 mission, 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 mission varieties. The simplest option to get began with Storybook is to put in it right into a pre-existing software and run a easy command on the root of your mission:

npx storybook@newest init

The above command will have a look at your mission dependencies and decide essentially the most acceptable option to set up Storybook.

When you need assistance figuring out whether or not your mission would assist Storybook, learn by means of the Frameworks page within the documentation.

Observe: you’ll be able to set up Storybook manually, however this usually ends in 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 software. Additional customization will probably be required to make sure Storybook behaves in a fashion aligned along with your software’s know-how stack.

Configuring Storybook is primarily finished by means of the fundamental.js file. You possibly can specify all the things right here — from how documentation is offered, to extending Storybook’s UI with add-ons. You possibly can even lengthen Webpack.

Storybook helps TypeScript out of the field, however it’s essential to arrange your CSS structure. Many flavors of CSS are supported. You could find 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 primary React software. We’ll be utilizing Create React App for this text, although different frameworks are additionally supported. Let’s ensure your software is working accurately by operating npm run begin. It’s best to see one thing just like what’s pictured beneath.

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

npx storybook@newest init

The script will do a little bit of considering after which immediate you to verify a couple of particulars. Storybook is wise sufficient to detect that we’re utilizing Create React App (CRA), and it’ll probably must replace a couple of dependencies to work seamlessly along with your mission. Hit Y while you see the immediate pictured beneath.

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

At this level, it’s value what’s modified in our mission. Storybook added a .storybook folder the place your configuration information reside. You’ll additionally discover a tales folder added to the src listing. There are usually three associated information 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 information 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 surroundings 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 referred to as storybook-static: it is a “printed” Storybook that may be made publicly accessible.

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

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

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

There are a couple of 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 mostly completely different for every mission sort. docs tells Storybook to doc parts robotically.

I might extremely advocate reading the Configure page within the Storybook docs for extra details about what will be dealt with by means of fundamental.js.

Deciding on Storybook Add-ons

You possibly can consider Storybook add-ons as “plugins”. They’re pre-written packages that stretch 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 mission and your staff’s targets. There are successfully two forms of add-ons: UI-based and preset-based. “UI-based” add-ons customise the useful look of Storybook. “Preset-based” add-ons permit you to combine with different applied sciences like TypeScript or Tailwind. You could find a set of all add-ons on the Integrations web page.

Observe: some add-ons are maintained by the Storybook staff, whereas others are community-driven. Group-driven add-ons might yield surprising outcomes or might not be suitable with the most recent model of Storybook.

Earlier than you go on the hunt for a set of add-ons you are feeling will probably be greatest to combine, be sure you check out what Storybook installs by default:

addons: [
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "@storybook/preset-create-react-app",
    "@storybook/addon-onboarding",
    "@storybook/addon-interactions",
  ],

1. @storybook/addon-links helps you to hyperlink Tales to construct prototypes.
2. @storybook/addon-essentials embody all add-ons situated right here: https://storybook.js.org/integrations/tag/essentials/.
3. @storybook/preset-create-react-app is a preset-based add-on that enhances the mixing with CRA.
4. @storybook/addon-onboarding gives a guided tour of Storybook options.
5. @storybook/addon-interactions lets you debug the interplay state of your parts. When 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 finished by including the add-on to the addons key in fundamental.js:

addons: [
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "@storybook/preset-create-react-app",
    "@storybook/addon-onboarding",
    "@storybook/addon-interactions",
    "@storybook/addon-a11y",
  ],

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

You possibly can see now that the “Accessibility” tab has been added to all story cases and is already flagging issues with a11y in our parts. “UI-based” add-ons solely require just a little configuration. “Preset-based” will be extra advanced. The rationale for that is that “preset-based” add-ons usually want additional configuration, similar to:

• inserting configuration information on the root of your mission
• configuring choices / Webpack configurations that should align along with your CRA software settings

This could trigger lots of friction, and remediation can rely upon the framework of selection. Use warning when extending Storybook with “preset-based” add-ons and guarantee parity along with your software.

Writing and Documenting Part Tales

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

These props will be configured to output variations of every part. This permits engineers to work together with prop values inside the Storybook UI. Let’s evaluate our Button story that was added by means of 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 Major = {
  args: {
    main: true,
    label: 'Button',
  },
};

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

export const Giant = {
  args: {
    dimension: 'massive',
    label: 'Button',
  },
};

export const Small = {
  args: {
    dimension: '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 primary part. It’s the place important settings are configured. Most of them are self-explanatory. Nonetheless, I want to name out the next:

• Parameters are a set of static, named metadata a few story, sometimes used to manage 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 will probably be output in Storybook below the Button part, and you may work together with them as wanted.

Understanding Decorators goes a good distance in the event you plan on constructing extra advanced tales. A decorator gives a option to wrap tales in additional context and performance. Tales will be handed to a decorator by setting the decorator key within the story parameters:

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

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

Tales may also eat parts from different Tales. Simply be conscious that this can depend on how your part renders and the way a lot element you propose on including to your software general.

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

Writing a Story for our software

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

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

Create these information 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 }) => (
  <footer>
    <div className="footer">
      {showCopyRight && (
        <div>
          <span>
            <span function="img" aria-label="copy">©️</span> 2018 {siteOwner}.
          </span>
        </div>
      )}
    </div>
  </footer>
);

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,
  },
};

It is a comparatively contrived instance, nevertheless it illustrates how simple it’s so as to add a narrative. Add the above to Footer.tales.js. The outcome will probably be an auto-documented, multi-variant story that enables customers to work together with the part’s props.

Attempt updating the siteOwner worth immediately within the story controls. If you wish to model the Footer, import footer.css into Footer.jsx and reference the category names. When you’re all in favour of seeing how the part behaves in your React software, 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 regionally on Storybook, because the configuration is tracked by means of your most well-liked model management system. Nonetheless, 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 information which can be outputted right into a construct folder. Fortunately, the Storybook staff has made this comparatively simple to realize. All you 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 method of publishing a damaged Storybook. Now that we’ve a manufacturing construct, we want 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.

When you don’t plan on establishing Chromatic (really helpful), I like to recommend operating with GitHub Pages, as you’ll be able to add a GitHub Action to make quick work of the configuration and setup.

Setting Up Chromatic for VRT

Chromatic is a strong instrument that lives alongside Storybook. The Storybook staff maintains Chromatic, so integrating the instrument into your pre-existing software 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 surroundings. The applying permits for seamless collaboration inside groups and goes a protracted option 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 Mission Token. Subsequent, you’ll want to put in the Chromatic npm package deal into your mission:

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’ve a .env file with the next surroundings variable outlined: CHROMATIC_PROJECT_TOKEN. You possibly can add the Mission Token out of your Chromatic account as the worth.

Run npm run chromatic. This can publish your Storybook to your Chromatic mission. You possibly can then entry a powerful UI to evaluate parts and their modifications. The issue with this setup is that you just’ll must run Chromatic every time you modify parts.

This can be okay for smaller tasks, however committing modifications to your software and having a CI pipeline deal with this tough work is much better. Chromatic CI integrates immediately into pull requests.

When you’re utilizing GitHub, you’ll be able to rapidly stand 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 stand up and operating.

You’ve now printed a part library that runs UI Exams and Evaluations every time you commit modifications to your parts.

Conclusion and Takeaways

Storybook and Chromatic instruments will empower your staff 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 staff 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.