Getting Started with Storybook for React Developers

Have you ever needed an efficient way to review and test React UI components in isolation? If you are new to the world of React, you probably rely on repeatedly rendering full app pages to check each small change. But there is a much better approach…

Content Navigation show

This is where Storybook comes in!

Storybook is an open source tool used by over 100,000 developers to build reusable React component libraries faster. Companies like Airbnb, Dropbox, Lyft, and GitHub all use Storybook to develop consistent, complex UIs at scale while saving time and reducing bugs.

In this guide, I‘ll show you how to get started with Storybook and demonstrate why it has become an essential tool for React teams who care about building quality user interfaces.

Here‘s what I‘ll cover:

  • What is Storybook and why should React developers care about it?
  • Setting up Storybook in a new or existing React project
  • Writing visual stories to test components
  • Powering up stories with addons like controls, actions, docs
  • Scaling up with additional tools like Jest testing, CI/CD, MDX docs

And much more!

Let‘s dive in…

What is React Storybook and Why Use It?

Storybook is tool for isolating and interacting with individual UI components outside of the main app. This serves several key purposes:

Visual Testing

With Storybook you can visually test components by rapidly viewing them in a wide range of configurations. Rather than needing to manually setup complex app states again and again, you can storyboard the edge cases once.

For example, an e-commerce site may have dozens of variants for something like a <ProductCard /> component. With Storybook you can mock these out and ensure it renders properly every time:

// ProductCard.stories.js

export const Default = () => <ProductCard />;

export const OnSale = () => <ProductCard salePrice={25} />  

export const OutOfStock = () => <ProductCard inStock={false} />

Document Variants

Beyond testing, Storybook serves as excellent documentation for how components can be used. At a glance you can see all allowed props, event handlers, variant styles etc. Stories serve as live usage references!

Develop Out of Context

Since Storybook isolates components outside of the app, it promotes developing highly decoupled and reusable elements from the start. Components owned by a single team can be perfected before integration.

Improve Team Collaboration

With Storybook as single source of truth for components, it becomes easier for large teams to work together and stay in sync. New hires can quickly understand components without digging through the app. Changes can be reviewed visually via pull requests.

Storybook transforms how teams build, use, and scale React component libraries. The result is more modular code, fewer UI bugs, and accelerated development!

Setting Up Storybook with React

Let‘s walk through getting Storybook integrated into a React project.

First, we‘ll initialize a new app using Create React App. If you already have an existing project, feel free to use that instead: 

npx create-react-app my-storybook-app

Next we‘ll scaffold Storybook configuration and dependencies with a single command:

npx -p @storybook/cli sb init

By default this will automatically detect we are using React and make the necessary adjustments. We now have a .storybook config directory and some new npm scripts.

To start the dev server we can run:

npm run storybook

Now navigate to http://localhost:6006 to access Storybook!

Out of the box you will see some demo component stories that come included. Let‘s replace this with our own story as an example.

Writing Your First Story

A component story is simply a JavaScript module that renders different configurations of that component for development and testing purposes.

For example, let‘s make a basic <MyComponent> and story file:

// MyComponent.js

export default function MyComponent() {
  return (
    <div>Hello World!</div>  
  );
}
// MyComponent.stories.js

import MyComponent from ‘./MyComponent‘;

export default {
  title: ‘Components/MyComponent‘
};

export const Primary = () => <MyComponent />;

The key things to notice are:

  • Default export controls the sidebar grouping
  • Named exports like Primary define stories
  • Stories are just functions that return JSX

Now when we load up Storybook, MyComponent will appear as a story under the "Components" group!

Documenting Component Variants

As we build reusables UI elements, Storybook helps us thoroughly test by visually documenting the different configurations and states.

For example, a common <Button /> component can have many potential variations:

// Button.js

export const Button = ({
  disabled,
  size,
  label  
}) => {
  // ...
}

Rather than needing to manually handle these variants across different pages, we can storyboard them once:

// Button.stories.js

export default { 
  title: ‘Forms/Button‘
}

export const Default = () => 
  <Button>Submit</Button>

export const Primary = () =>
  <Button variant="primary">Submit</Button>  

export const Disabled = () =>
  <Button disabled>Submit</Button>

export const Small = () =>
  <Button size="small">Submit</Button>

Now we can instantly preview the Button component in all its potential states and sizes without any redundant configuration!

As the component evolves, additional stories get added documenting the new variants. This saves so much time over testing manually.

Streamlining Stories with Args

As stories grow, it helps to externalize the component props to keep previews clean and reusable:

const Button = ({size, children}) => {}

export const Large = (args) => <Button {...args} /> 

Large.args = {
  size: ‘large‘,
  children: ‘Large Button‘
}

Args will also become useful for handling advanced Storybook addons…

Level Up Your Stories with Addons

In addition to visual testing, Storybook boasts a robust addon ecosystem to level up what‘s possible. Some of the most popular include:

Controls Addon

Controls allows you to dynamically modify component props in the UI to see changes. For example you could tweak colors or sizes without needing to explicitly write a story variant for every case:

Storybook Controls Addon

To add, first install the addon:

npm i -D @storybook/addon-controls

Then import and register it in .storybook/main.js:

module.exports = {
  "addons": [
    "@storybook/addon-controls"
  ]
}

Finally decorate your stories with argTypes metadata:

export const Large = (args) => <Button {...args} /> 

Large.args = {
  // ...
}

Large.argTypes = {
  size: {
    control: {
      type: ‘select‘,
      options: [‘small‘, ‘medium‘, ‘large‘],
    }
  }
}

Now customize props live!

Actions Addon

The actions addon logs component events like clicks, hovers etc. This is great for testing and debugging user interactions:

Storybook Actions Addon

Usage is similar to controls. Install the addon then wrap event handlers:

import { action } from ‘@storybook/addon-actions‘;

export const Large = (args) => (
  <Button 
    {...args}
    onClick={action(‘clicked‘)} 
  />
);

Now interact and observe!

There are many more addons available like backgrounds, accessibility checks, docs generation etc. They help transform Storybook into a Swiss army knife for components!

Additional Tips and Integrations

Here are some other awesome things you can do:

Automatic Visual Testing

Storyshots lets you integrate Storybook with Jest for automatic visual regression testing. See changes instantly in CI.

Theming Support

Ensure components work across different themes by hot swapping via Storybook decorators.

Docs Generation

Annotate components in MDX-flavored documentation stories visible alongside the canvas.

CI/CD Pipelines

Include Storybook builds, screenshot tests, and hosting in your GitLab, GitHub or Jenkins pipelines.

Static Hosting

Publish components for the world to see via GitHub Pages, Netlify, and automated versioning based on GIT history.

Addon Ecosystem

Accessibility checks, translations, state management… over 600 community addons extend what‘s possible!

As you can see Storybook is extremely powerful for handling everything related to modular UIs at enterprise scale and beyond!

Key Takeaways

We‘ve just scratched the surface of what Storybook offers React developers. To recap:

✅ Visual test cases help you build components faster and catch bugs early

✅ Live documentation helps you develop truly reusable UI building blocks

✅ Isolated dev environments allow perfecting components outside of main app

✅ Powerful addons extend Storybook into your entire workflow

✅ Cloud hosting and distribution options help scale component libraries across teams

Everything gets easier about using React when leveraging Storybook – I highly recommend giving it a shot!

For more information be sure to check out Storybook‘s excellent documentation which covers way more best practices, examples and customization tips.

Let me know if you have any other questions!

Tags: