Scaffolding a React Component Library with Storybook (Using TypeScript)

When a company develops and releases a new product onto its platform, users expect this product to deliver an experience similar to another product (on the platform) they have worked with. For example, many people, including yourself, are probably familiar with at least one of Google's collaborative office tools, such as 

. Now, suppose Google announces a new collaborative office tool at Google I/O. If you decide to use this tool, then you may notice how much faster it takes for you to learn this tool, along with its shortcuts and tricks, because the interface contains features that you have previously interacted with in other tools. Across each tool, the appearance of these features, such as the editing toolbar and sharing dialog, remains consistent since they draw upon the same set of foundational elements, controls, colors, typography, animations, etc.

By building a component library, we can centralize all reusable components at one location and access these components from any of our products. Furthermore, pairing a component library with a design system unifies every product within the platform under a singular brand identity. For distributed teams that work on products independently of one another, this allows teams to follow the same design principles/philosophies/patterns, share code and create components in isolation. Writing components in an environment outside of our application makes them flexible and adaptable to any specific layout requirements. This way, the component's design can account for both known and unforeseen use cases. Anytime designers, developers and product managers contribute to the library and update the components, those changes immediately propagate down to the products using those components. 

With so many different stakeholders involved, we need to build durable components that are thoroughly tested and well-documented. A popular open-source tool for organizing and building components in isolation is 

, which comes with a sandbox for previewing/demoing components and mocking use cases to capture different states of a component in 

. Documenting these use cases as stories especially helps in onboarding new team members. Storybook has integrations with different front-end libraries/frameworks: 

, etc. Additionally, if you need functionality that Storybook doesn't already provide, then you can create 

Below, I'm going to show you how to add Storybook to your component library.

To get started, clone the following repository:

$ git clone -b library https://github.com/newline-sandbox/react-d3-charts.git

This repository contains a component library with customizable D3 visualizations written in React and TypeScript. Currently, this repository only has one visualization component, a scatterplot.

Inside of the project directory, install the dependencies:

For this tutorial, we will be adding Storybook to this library and writing stories for its scatterplot component. 

Add Storybook to the library with Storybook CLI. As of Storybook v6.0, Storybook CLI automatically detects whether the project is TypeScript-based and configures Storybook to support TypeScript without any additional configuration. 

This command creates the following directories and files within the project:

, several Storybook dependencies are now listed under 

Along with these new dependencies, several NPM scripts are added for running Storybook locally and building Storybook as a static web application (to host on a cloud service and publish online).

 and automatically opens Storybook inside the browser. Once Storybook loads, you will be presented an introductory page that contains links to additional learning resources.  

: You can modify this page by editing the 

 file defines a component's stories. To view a component's stories in Storybook, click on the item in the left sidebar that corresponds to the component to expand a list of its stories. For example, if you click on the "Button" item, then the canvas displays the first story listed for the 

 component. Rendered as an iframe, the canvas allows components to be tested in isolation. Altogether, four stories appear beneath the "Button" item in the sidebar: 

Each story describes how certain parameters affect the rendering of the component. To understand what this means, let's look inside the 

import React from 'react';
import './button.css';

export interface ButtonProps {
  /**
   * Is this the principal call to action on the page?
   */
  primary?: boolean;
  /**
   * What background color to use
   */
  backgroundColor?: string;
  /**
   * How large should the button be?
   */
  size?: 'small' | 'medium' | 'large';
  /**
   * Button contents
   */
  label: string;
  /**
   * Optional click handler
   */
  onClick?: () => void;
}

/**
 * Primary UI component for user interaction
 */
export const Button: React.FC<ButtonProps> = ({
  primary = false,
  size = 'medium',
  backgroundColor,
  label,
  ...props
}) => {
  const mode = primary ? 'storybook-button--primary' : 'storybook-button--secondary';
  return (
    <button
      type="button"
      className={['storybook-button', `storybook-button--${size}`, mode].join(' ')}
      style={{ backgroundColor }}
      {...props}
    >
      {label}
    </button>
  );
};

import React from 'react';
import { Story, Meta } from '@storybook/react';

import { Button, ButtonProps } from './Button';

export default {
  title: 'Example/Button',
  component: Button,
  argTypes: {
    backgroundColor: { control: 'color' },
  },
} as Meta;

const Template: Story<ButtonProps> = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  primary: true,
  label: 'Button',
};

export const Secondary = Template.bind({});
Secondary.args = {
  label: 'Button',
};

export const Large = Template.bind({});
Large.args = {
  size: 'large',
  label: 'Button',
};

export const Small = Template.bind({});
Small.args = {
  size: 'small',
  label: 'Button',
};

 and uses them to render the component. It serves as a template for defining a story. To keep the example simple, 

 represents props that are passed directly to the component, but they can be modified inside of the 

 function for more complex examples. Each story makes a new copy of this template via 

 to set its own properties. To specify a story's 

 property on the story's copy of the template function, and assign this property an object with the values needed for rendering the component.

 (passed directly to the component within the story's 

If you want to experiment with different prop values, then adjust the props within the "Controls" panel below the canvas. Only props of primitive types, such as booleans and strings, are dynamically editable. When you enter "red" into the 

 input field, the button's background color changes to red.

If you switch from "Controls" to "Actions," then you can see logs of event handlers executed as a result of user interactions. For example, the 

 element. When you click the button in Storybook, the panel will print information about that 

Everything mentioned above also applies to the stories 

If you press the "Docs" tab, then Storybook shows information about the 

 component, such as prop descriptions, the code required to render the component shown in a story, etc.

The prop descriptions come from inline comments written in the props' exported TypeScript interface.

First, let's remove the example stories created during the initialization process.

 file with the contents of the library's 

$ touch src/stories/Introduction.stories.mdx

import { Meta, Description } from "@storybook/addon-docs/blocks";
import README from "../../README.md";

<Meta title="Example/Introduction" />

<Description>{README}</Description>

 provides the building blocks for writing documentation pages. For now, the introductory page will have a webpage title of "Example/Introduction" and will render the extracted contents of the README file to both "Canvas" and "Docs."

Now, let's write some stories for our library's 

$ touch src/stories/Scatterplot.stories.tsx

Inside of this file, add stories to reflect the following basic use cases for the 

For all of the stories to access data fetched from a remote source, we must set a global loader, which runs before the rendering of the stories, inside of the 

import { csv } from "d3-fetch";
import { nanoid } from "nanoid";

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  },
};

const fetchScatterplotData = async () => {
  try {
    return await csv(
      "https://gist.githubusercontent.com/curran/a08a1080b88344b0c8a7/raw/0e7a9b0a5d22642a06d3d5b9bcbad9890c8ee534/iris.csv",
      ({ petal_length: x, petal_width: y, species }) => ({
        id: nanoid(),
        x: +x,
        y: +y,
        species,
      })
    );
  } catch (err) {
    console.error(err);

    return [];
  }
};

export const loaders = [
  async () => ({
    scatterplotData: await fetchScatterplotData(),
  }),
];

 contains the fetched and processed Iris data, which will be available to the stories of the 

 can be accessed by any story template in the project via the template's second argument, the story context, which has a 

 and export an object with metadata about the component. The pages of the component's stories will be prefixed with the webpage title "Example/Scatterplot."  

import React from "react";
import { Story, Meta } from "@storybook/react";

import { Scatterplot, ScatterplotProps } from "../components/Scatterplot";

export default {
  title: "Example/Scatterplot",
  component: Scatterplot
} as Meta;

) with template arguments shared by all of the stories. In this case, each story's scatterplot will have the same dimensions (

) and render with the same axes' labels and data (

Write a template function that renders the 

 set for each story. Since the default value of 

 is an empty array, we must explicitly check for a flag 

, which will notify the template function to use this empty array only for the "Empty" story. For the other stories, use the scatterplot data fetched by the global loader.

interface TemplateProps extends ScatterplotProps {
  isEmpty?: boolean;
}

const Template: Story<TemplateProps> = ({ isEmpty, ...args }, { loaded }) => {
  return (
    <Scatterplot
      {...args}
      data={isEmpty ? args.data : loaded ? loaded.scatterplotData : args.data}
    />
  );
};

 is undefined when accessing the component's docspage. Unfortunately, all of the inline-rendered stories will be empty because loaders are experimental and 

not yet compatible with inline-rendered stories in Storybook Docs

Write the stories. For the "Default" story, just use the base arguments. For the "Empty" story, make sure to notify the template function to use the default empty 

 array. For the "Legend" story, set two additional fields to 

 (a key to access a record's category) and another for 

 (a list of colors to visually differentiate categories).

export const Default = Template.bind({});
Default.args = {
  ...BASE_ARGS,
};

export const Empty = Template.bind({});
Empty.args = {
  ...BASE_ARGS,
  isEmpty: true,
};

export const Legend = Template.bind({});
Legend.args = {
  ...BASE_ARGS,
  categoryKey: "species",
  categoryColors: ["#754668", "#982649", "#9395d3"],
};

import React from "react";
import { Story, Meta } from "@storybook/react";

import { Scatterplot, ScatterplotProps } from "../components/Scatterplot";

export default {
  title: "Example/Scatterplot",
  component: Scatterplot,
  argTypes: {
    backgroundColor: { control: "color" },
  },
} as Meta;

const BASE_ARGS = {
  dimensions: {
    get width() {
      return 560 - this.margins.left - this.margins.right;
    },
    get height() {
      return 500 - this.margins.top - this.margins.bottom;
    },
    margins: {
      top: 10,
      right: 30,
      bottom: 75,
      left: 60,
    },
  },
  labels: {
    xAxis: "Petal Length (cm.)",
    yAxis: "Petal Width (cm.)",
  },
  xAccessorKey: "x",
  yAccessorKey: "y",
};

interface TemplateProps extends ScatterplotProps {
  isEmpty?: boolean;
}

const Template: Story<TemplateProps> = ({ isEmpty, ...args }, { loaded }) => {
  return (
    <Scatterplot
      {...args}
      data={isEmpty ? args.data : loaded ? loaded.scatterplotData : args.data}
    />
  );
};

export const Default = Template.bind({});
Default.args = {
  ...BASE_ARGS,
};

export const Empty = Template.bind({});
Empty.args = {
  ...BASE_ARGS,
  isEmpty: true,
};

export const Legend = Template.bind({});
Legend.args = {
  ...BASE_ARGS,
  categoryKey: "species",
  categoryColors: ["#754668", "#982649", "#9395d3"],
};

For a final version of this tutorial, check out the GitHub repository 

Try integrating Storybook into your own component library!

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Scaffolding a React Component Library with Storybook (Using TypeScript)

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript