37590801?s=460&v=4

A software engineer who dreams about non-electric sheep and autonomous vehicles and likes to champion security.

Software Engineer

Dan Arias

Learn how to build a component library with Vue and Storybook to create modular and reusable components.

Using Storybook with VueJS

Learn how to build a component library with React and Storybook to create modular and reusable components that can be shared across projects.



Storybook is a development environment for UI components. It let us browse a component library, view the different states of its components, and interactively develop and test them. Storybook runs outside of our application; therefore, we can develop UI components in isolation without worrying about any project dependencies and requirements.

For the scope of this introductory blog post, we are going to demonstrate how to start a new project using Storybook to get familiar with its platform and mechanics stemming from the "Storybook-Driven Development" practices that we have [developed at Auth0 within the Customer Success Infrastructure team](https://auth0.com/blog/our-engineering-experience-with-react-and-storybook/).

In a previous blog post, we created the [foundation of our project by setting up a component library](https://auth0.com/blog/setting-up-a-component-library-with-react-and-storybook/). If you have been following along you may continue to build upon where we left. Otherwise, feel free to clone the [Marvel Bank app repo](https://github.com/auth0-blog/marvel-bank-app) and checkout the `A-Tale-of-Reusability-Part-1` branch which includes all the work that we've done in the first part.

```shell
git clone https://github.com/auth0-blog/marvel-bank-app.git
cd marvel-bank-app/
git checkout A-Tale-of-Reusability-Part-1
```

Let's start by learning how we can setup Storybook in a brand-new `create-react-app` project.

<blockquote class="twitter-tweet" data-lang="en"><p lang="en" dir="ltr">Thrilling news: the next chapter for <a href="https://twitter.com/storybookjs?ref_src=twsrc%5Etfw">@storybookjs</a> with full-time maintenance and a bigger team. I&#39;m over the moon!<a href="https://t.co/xWL3Gp5dzI">https://t.co/xWL3Gp5dzI</a> <a href="https://t.co/T1JJfzNGp6">pic.twitter.com/T1JJfzNGp6</a></p>&mdash; shilman (@mshilman) <a href="https://twitter.com/mshilman/status/1021411688749326338?ref_src=twsrc%5Etfw">July 23, 2018</a></blockquote>
<script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

## Setting Up Storybook

There are two options available to us for adding Storybook: we can install the platform globally or we can start the platform locally. Which installation path should we take?

Our colleague, Matt Machuga, an Engineering Lead in our R&D Team, suggests that "CLI tools that are not project specific are good candidates for global installation." In practice, Matt tries to "scope everything else into local. So the version being used is kept recorded and installed via `npm install`."

We have different options for installing Storybook: a global install, an install using `npx`, and a local manual install. I'll explore those options with you and let you decide which one is right for you. However, I do recommend that you walk with me through the local manual install as it let us learn a great deal about how Storybook works.

### Install `@storybook/react` Globally

To install and run Storybook from your shell follow these quick steps:

- In the shell, make sure that your project directory your current working directory, `marvel-app`.

- Next, install `@storybook/cli` globally:

```shell
npm i -g @storybook/cli
```

> Above, we used a few `npm` argument shortcuts. `i` stands for `install` and `-g` stands for the flag `--global`.

- Restart your shell. You can do that by closing the existing window or tab and opening a new one.

- Finally, with `marvel-app` again as your current working directory, run the `getstorybook` command to have the Storybook CLI scaffold all the necessary files and folders to work with Storybook in your project. These include the `.storybook` folder under the root project and the `stories` folder under the `src` folder.

Let's see how this can be done without a global install using `npx`.

### Install `@storybook/react` Using `npx`

We can emulate the same behavior of the global installation of Storybook but without the actual global installation. If you have `npm >= 5.2` installed in your system, you have `npx` available!

- In the shell, make sure that your project directory your current working directory, `marvel-app`.

- Run the `getstorybook` command using `npx`:

```shell
npx @storybook/cli getstorybook
```

[`npx` downloads and executes the binary on the fly](https://alligator.io/workflow/npx/). The Storybook CLI will run and create all the necessary files and folder in your project just as in the previous section. This method is the fastest way to get up and running!

<include src="TweetQuote" quoteText="npx lets us run one-off invocations of CLI tools available in the npm registry without local installation."/>

Now, let's explore what the Storybook creators call the "slow start", the local manual installation of Storybook. Through that process, we'll learn how the folders and files installed by the Storybook CLI work.

### Install @storybook/react manually

In the shell, let's run the following command:

npm:

```shell
npm i -D @storybook/react
```

> Another `npm` argument shortcut. `-D` stands for `--save-dev`.

### Storybook NPM Script

After `@storybook/react` has finished its installation. We need to add the following `script` to `package.json` to run Storybook:

```json
"storybook": "start-storybook -p 9001 -c .storybook"
```

```json
{
  "name": "marvel-bank",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "node-sass-chokidar": "^1.3.3",
    "npm-run-all": "^4.1.3",
    "react": "^16.4.1",
    "react-dom": "^16.4.1",
    "react-scripts": "1.1.4"
  },
  "scripts": {
    "build-css": "node-sass-chokidar src/ -o src/",
    "watch-css":
      "npm run build-css && node-sass-chokidar src/ -o src/ --watch --recursive",
    "storybook": "start-storybook -p 9001 -c .storybook",
    "start-react": "react-scripts start",
    "start": "npm-run-all -p watch-css start-react",
    "build-react": "react-scripts build",
    "build": "npm-run-all -s build-css build-react",
    "test": "react-scripts test --env=jsdom",
    "eject": "react-scripts eject"
  },
  "devDependencies": {
    "@storybook/react": "^3.4.8"
  }
}
```

### Create A Storybook Configuration File

[As explained in the Storybook docs](https://storybook.js.org/basics/guide-react/), the platform is flexible and can be configured in different ways. We can control that configuration through a config directory. In our `storybook` `npm` script, we added a `-c` option followed by `.storybook` which tells Storybook to look for configuration options in the `.storybook` hidden folder.

Having our project root folder as the current working directory, let's go ahead and create that folder:

macOS/Linux/Windows:

```shell
mkdir .storybook
```

Next, we need to create a `config.js` file inside `.storybook` to hold the configuration. Let's start it with the following code:

```javascript
// .storybook/config.js

import { configure } from "@storybook/react";

function loadStories() {
  require("../src/stories/index.js");
  // You can require as many stories as you need.
}

configure(loadStories, module);
```

Storybook works in a similar way to testing tools. The `config.js` loads the `configure` method, which takes as argument a function called `loadStories` and a `module`. `loadStories` will have **stories** defined on its body. A **story** describes the single state of a component. We want to write a story for each state a component will have.

> Stories are similar to how [`it` methods run tests](https://jestjs.io/docs/en/api.html#testname-fn-timeout) in testing libraries like Jest.

We are going to write and load the stories from `../src/stories/index.js` which will be under the root folder. Let's create such folder and file to write our first story. Under the `src` folder let's create a `stories` subfolder and then create an `index.js` file inside it.

> `.storybook` is used solely for configuration files. Do not put your `stories` folder inside this hidden folder.

### Writing a Story in Storybook

Open the recently created `index.js` under `src/stories` and populate it with the following code:

```javascript
// src/stories/index.js

import React from "react";
import { storiesOf } from "@storybook/react";
```

So far, there's not much going on. We import `React` and a `storiesOf` method that will help us create stories for a component. We need that component. Let's import `Button` here:

```javascript
// src/stories/index.js

import React from "react";
import { storiesOf } from "@storybook/react";
import Button from "../../src/features/common/Button";
```

Storybook has a declarative language. What we are going to do next is to tell it that we want stories of `Button`:

```javascript
// src/stories/index.js

import React from "react";
import { storiesOf } from "@storybook/react";
import Button from "../../src/features/common/Button";

storiesOf("Button", module);
```

If we were thinking in terms of an actual book, this is the book's binding and cover. We need to fill it with pages full of stories. We do that declarative too using the `add` method:

```javascript
// src/stories/index.js

import React from "react";
import { storiesOf } from "@storybook/react";
import Button from "../../src/features/common/Button";

storiesOf("Button", module).add("with text", () => (
  <Button label={`Continue`} />
));
```

`add` acts like adding a chapter to a book that has a story. We want to give each chapter a title. In this case, we are creating a story titled `with text`. `add` takes as argument the story title and a function that renders the component being staged.

We have the foundation of writing a story. It's time to see if everything is working by running Storybook.

<include src="TweetQuote" quoteText="Similar to testing, Storybook uses declarative language to let us write stories that define the expected presentation and behavior of our components."/>

### Running Storybook

In the shell, run the following command:

npm:

```shell
npm run storybook
```

If everything runs successfully, we will see this message in the shell:

```shell
info Storybook started on => http://localhost:9001/
```

Let's open that URL, [`http://localhost:9001/`](http://localhost:9001/) in the browser. Let it load... and there we have it in its full glory: our own Storybook!

Right now it's pretty basic but this is a great start!

![A working Storybook](https://images.ctfassets.net/23aumh6u8s0i/3UAjbi2EhTJSdzs2kZ11UB/3d29231861b685150289a990396fe2f7/first-storybook)

This is a good time to make another commit to address the integration of Storybook:

```shell
git status
git add .
git commit -m "Integrate Storybook"
```

## Integrating CSS with Storybook

To communicate the presentation and state of the `Button` component, we need to add styling to it. Under `src/features/common`, let's create `Button.scss` and populate it with the following code:

```scss
// src/features/common/Button.scss

@import "../../styles/theme";

.Button {
  display: flex;
  flex-direction: row;
  justify-content: center;
  align-items: center;

  height: 40px;
  width: 160px;
  border: 2px solid $blue;
  border-radius: 60px;

  font-family: $primary-font;
  font-size: 16px;
  color: $blue;
  letter-spacing: 1.27px;
  text-align: center;

  text-transform: uppercase;
}
```

Next, let's import that stylesheet into `Button.js` and add `Button` as a `className` for the `Button` component:

```javascript
import React from "react";

import "./Button.css";

const Button = props => <div className="Button">{props.label}</div>;

export default Button;
```

Let's save our work. We should see now how Storybook has refreshed the board and shows the updated component with styling applied:

![Storybook staged a component with styling applied.](https://images.ctfassets.net/23aumh6u8s0i/1AvF1A0X8rNWYpCg5IP8YE/02e3f25e86dc8b04bb1fdc50a6eec788/storybook-with-component-with-style)

Just like with `create-react-app`, we can make changes to the structure, content, or style of a component and they will be updated in Storybook. Let's change the background, font color and border of `Button` to see this in action:

```scss
// src/features/common/Button.scss

@import "../../styles/theme";

.Button {
  display: flex;
  flex-direction: row;
  justify-content: center;
  align-items: center;

  background: $green;

  height: 40px;
  width: 160px;

  border-radius: 60px;

  font-family: $primary-font;
  font-size: 16px;
  color: white;
  letter-spacing: 1.27px;
  text-align: center;

  text-transform: uppercase;
}
```

Let's save our work again and observe the changes:

![Updated component in Storybook](https://images.ctfassets.net/23aumh6u8s0i/6wpOxGNqq4MFoJOklUpsFq/dedd7dc955550d85196c93ac54114c53/component-updated-in-storybook)

Style changes are well integrated into our workflow. It's truly amazing that we can preview our components this way without having to run our application. We can develop our component in isolation and then use them in the app whenever we want.

<include src="TweetQuote" quoteText="Just like with `create-react-app`, we can make changes to the structure, content, or style of a React component and it will be updated in Storybook! We can visualize our components without running our app."/>

As discussed before, `Button` has three different presentations. The best way to organize that would be through CSS classes and props.

We want the `Button` component to know:

- Its active state: `active` / `disabled`
- Its style state: `fill` / `no-fill`

Let's update `Button.scss` with classes that represent these states:

```scss
// src/features/common/Button.scss

@import "../../styles/theme";

.Button {
  display: flex;
  flex-direction: row;
  justify-content: center;
  align-items: center;

  height: 40px;
  width: 160px;

  border-radius: 60px;

  font-family: $primary-font;
  font-size: 16px;

  letter-spacing: 1.27px;
  text-align: center;

  text-transform: uppercase;
}

.active {
}

.disabled {
  border: 2px solid $color-text-lighter;

  color: $color-text-lighter;
  letter-spacing: 1.64px;
}

.fill {
  background: $green;
  box-shadow: 0 6px 8px 0 rgba(103, 194, 172, 0.5);

  color: $white;
  letter-spacing: 1.61px;
}

.no-fill {
  border: 2px solid $blue;

  color: $blue;
  letter-spacing: 1.27px;
}
```

Let's briefly review what we are doing here since it's important how this impacts component staging in Storybook:

- `.Button` has all the style properties shared by all instances of `Button`.
- `.active` is not in use right now but it could be used to provide unique properties to an active button.
- `.disabled` has the style properties for any instance of `Button` that becomes disabled.
- `fill` and `no-fill` apply distinct styling to an active button.

We need to integrate this style logic into our component logic as follows:

```javascript
// src/features/common/Button.js

import React from "react";

import "./Button.css";

const Button = props => (
  <div
    className={`Button ${
      props.active
        ? props.fill
          ? `active fill`
          : `active no-fill`
        : `disabled`
    }`}
  >
    {props.label}
  </div>
);

export default Button;
```

Using a combination of ternary operators we process the state of the button. If `props.active` is true, we check if `props.fill` is true or not and apply the corresponding class to the component. If `props.active` is false, there are no extra decisions to make and we apply the default `disabled` class.

To see this in action, let's create new stories in our Storybook!

## Creating Multiple Stories for a Component in Storybook

Let's head to `src/stories/index.js` and remove the current story that we have defined there, `with text`, as it isn't telling too much of a story:

```javascript
// stories/index.js

import React from "react";
import { storiesOf } from "@storybook/react";
import Button from "../../src/features/common/Button";

storiesOf("Button", module);
```

Next, let's add three new stories that clearly define the three presentations that we want `Button` to have depending on different state flags:

```javascript
// stories/index.js

import React from "react";
import { storiesOf } from "@storybook/react";
import Button from "../../src/features/common/Button";

storiesOf("Button", module)
  .add("active with fill", () => (
    <Button label={`continue`} fill={true} active={true} />
  ))
  .add("active with no fill", () => (
    <Button label={`sign up`} fill={false} active={true} />
  ))
  .add("disabled", () => <Button label={`continue`} active={false} />);
```

Let's save our work and we'll see Storybook update to show the three new stories under `Button`:

![Storybook showing three stories for a component](https://images.ctfassets.net/23aumh6u8s0i/5mnvrrwKAOaFwGotkdighn/e3b99cf5b9806db3cbc9a9b3e864b0c8/storybook-component-with-three-stories)

Each story renders an isolated instance of `Button` whose presentation depends on the `props` values that are passed to it. This is where we can see the value proposition of Storybook at play.

Without Storybook, we would need to add `Button` in our app somewhere and test its rendering by passing it different props. We would then need to remove the component. What if we need to change the structure or style of the component? We'd need to start that process all over again.

With Storybook, a component and all of its different states can be staged in a centralized location. What we see in Storybook will be seen in all the areas of the application that use the component, giving us confidence that we'll have presentational consistency throughout our application.

Let's click around the different stories and see how the component changes on each one. The UI Kit graphic definition of the user interface button is now alive in code.

"Button active with fill":

![Button active with fill](https://images.ctfassets.net/23aumh6u8s0i/67vqM3hxatu2OndYfYML5M/4feee7076faa1f382625e60a93a2b5d2/button-active-fill-state)

"Button active with no fill":

![Button active with no fill](https://images.ctfassets.net/23aumh6u8s0i/5CUP65tjJwCENcQxsUl2dH/d8edd5c0f1ab28d301cd1c97990898bd/button-active-no-fill)

"Button disabled":

![Button disabled](https://images.ctfassets.net/23aumh6u8s0i/1pNWNhqeyo8Dj2RpkLsYhl/cec1d9dd564a80c1f539e1f90c1c7812/button-disabled-view)

We have a solid `Button` component that communicates its state clearly through its presentation. Let's go ahead and commit these changes:

```shell
git status
git add .
git commit -m "Add three states to Button component"
```

### Next Steps

We have just barely scratched the surface of what can be done with Storybook! There's a lot more we can do with this amazing tool to make the creation, testing, and documentation of React components much faster. Storybook is also a highly configurable tool that relies on add-ons to boost its offerings.

At Auth0, different teams are making extensive use of Storybook in their React development and design processes. We are converging designers and developers into a Design Systems team that is letting us iterate faster and develop better products for our cherished customers.

Feel free to grab the source code of the project we have created so far from the [Marvel Bank App GitHub repo](https://github.com/auth0-blog/marvel-bank-app).

<include src="asides/AboutAuth0" />


Building a Component Library with React and Storybook

Learn how to set up a component library with React and Storybook to create modular and reusable components that can be shared across projects.



[Storybook](https://storybook.js.org/) is a development environment for UI components. It let us browse a component library, view the different states of its components, and interactively develop and test them. Storybook runs outside of our application; therefore, we can develop UI components in isolation without worrying about any project dependencies and requirements.

We've shared about [our experience using React and Storybook to better manage components](https://auth0.com/blog/our-engineering-experience-with-react-and-storybook/). In this post, we are going to explore how to organize a basic project, how to implement a style guide to help us achieve consistent branding, and how to build the foundation of a component library to make our components reusable and easy to maintain.

<blockquote class="twitter-tweet" data-lang="en"><p lang="en" dir="ltr">React is such a good idea that we will spend the rest of the decade continuing to explore its implications and applications.</p>&mdash; Guillermo Rauch (@rauchg) <a href="https://twitter.com/rauchg/status/801005961334943744?ref_src=twsrc%5Etfw">November 22, 2016</a></blockquote>
<script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

Let's start.

## Setting Up a React Project

We are going to use [`create-react-app`](https://github.com/facebook/create-react-app) to scaffold easily a new React application.

We can run `create-react-app` using `npx` which comes bundled with `npm 5.2+` and higher:

```shell
npx create-react-app marvel-bank
cd marvel-bank
```

If you use `npm 5.1` or earlier, you can't use `npx`. Instead, install `create-react-app` globally:

```shell
npm install -g create-react-app
```

And then run:

```shell
create-react-app marvel-bank
cd marvel-bank
```

> Notice that we are not running `npm start`. As mentioned earlier, we don't need to have a running React application to use Storybook.

Open the newly created `marvel-app` folder on your preferred code editor or IDE.

Within `marvel-bank`, the `src` folder contains the core business logic of our React application. Let's do some housekeeping and remove files and code that we don't need.

Open `src/App.js` and trim it like so:

```javascript
// src/App.js

import React, { Component } from "react";
import "./App.css";

class App extends Component {
  render() {
    return <div className="App" />;
  }
}

export default App;
```

Next, let's delete the following files:

- `App.test.js`
- `logo.svg`

> **Spoiler**: Storybook is an essential part of our testing stack as it makes testing a painless experience.

## Using a Style Guide for Consistent Branding

Using a style guide can lead to better application design and development. As explained by the [Marvel Design team](https://blog.marvelapp.com/style-guides-better-design-development/), "during the design phase style guides encourage consistency in the visual identity and help keep the interface system as logical as possible, which makes for a better UX."

What is a style guide anyway? Marvel has a solid answer: "A style guide clearly demonstrates how all interface elements and components are to be visually represented. It’s essentially a master reference for the user interface (UI)."

In this sense, a component library is part of a style guide as it presents our components visually and it is the single source of truth for each component (the master reference). To create a comprehensive style guide, the component library can be accompanied by design documents that define font styles and sizes as well as primary and secondary user interface colors. A Design Team usually creates a "UI Kit" that is handed to developers for implementation. _Shopify_ explains that a [UI kit is an assortment of graphic files](https://www.shopify.com/partners/blog/104547526-the-benefits-of-using-a-ui-kit) that include UI components (buttons, checkboxes, progress bars, etc.) for the purpose of defining and designing the user interface.

<include src="TweetQuote" quoteText="A component library helps you achieve consistent branding as it becomes the single source of truth for every component not only in the application but for all projects in the organization"/>

For the online banking app that we are going to start creating in this blog post, we are going to use a free Banking UI Kit that [Marvel created for Sketch](https://blog.marvelapp.com/free-banking-ui-kit-for-sketch/). To honor their effort, we named the app `marvel-bank`. The UI Kit looks as follows:

![Marvel Banking UI Kit](https://images.ctfassets.net/23aumh6u8s0i/5l9Xw1gUqAiHm7l7pEQXI1/4e372a21ee5778f75914ab05359a4d13/marvel-banking-ui-kit)

The UI Kit is designed for iOS, but we are going to adapt it for usage in a responsive web application. To make it easier for developers to understand the UI Kit, I created a design document where we can get the font names, the sizing, the color hex codes, etc: [Marvel Bank Style Guide](https://auth0.github.io/marvel-bank-styleguide/).

In the following excerpt, notice how is much easier to understand the guidelines that a developer would need to follow when creating the components presented in the UI Kit:

![Style guide design - typography and color palette](https://images.ctfassets.net/23aumh6u8s0i/1jmP0Jdc0o4Fb5VUnoNtgO/fe24cc9b198abb20e8403e4855b2621e/design-document)

If we need to implement a green button, we can consult the design document and copy the hex code of `$green`; however, it would be much easier if we could code the elements of the design document into our application in a modular way and reusable way. We have plenty of options to do that:

- We could use CSS variables, also known as [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables).
- We could use [SCSS](https://sass-lang.com/), [LESS](http://lesscss.org/), or [Stylus](http://stylus-lang.com/) to create style partials and variables.
- We could also opt for using [CSS-in-JS](https://reactjs.org/docs/faq-styling.html) through a library like [`styled-components`](https://www.styled-components.com/).

Our Team currently has been using a combination of Stylus and [CSS Modules](https://github.com/css-modules/css-modules) to manage the styling of the projects. React has unified the three layers of front-end development (HTML, CSS, and JavaScript) under one layer powered by JavaScript, JSX, and CSS-in-JS. For this post, however, we are going to rely on SCSS to create the modular components to minimize the development overhead.

> **Feedback:** Would you like to learn how we are using `styled-components` to create a modern component library? Let us know in the comments below and we could create a blog post about it.

<blockquote class="twitter-tweet" data-lang="en"><p lang="en" dir="ltr">Oh man and a <a href="https://twitter.com/storybookjs?ref_src=twsrc%5Etfw">@storybookjs</a> shoutout as well! Storybook has been indispensable for our component library.</p>&mdash; Maja Wichrowska (@majapw) <a href="https://twitter.com/majapw/status/997143616865828865?ref_src=twsrc%5Etfw">May 17, 2018</a></blockquote>
<script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

## Adding SCSS to `create-react-app`

We can [add `SCSS` support to `create-react-app`](https://techcookbook.com/react/use-scss-with-create-react-app) without having to `eject` to a custom setup. We need to install a few packages to help us achieve that goal:

NPM:

```shell
npm install --save node-sass-chokidar npm-run-all
```

[`node-sass-chokidar`](https://www.npmjs.com/package/node-sass-chokidar) is a thin wrapper around the node-sass executable to use [chokidar](https://github.com/paulmillr/chokidar) instead of [Gaze](https://github.com/shama/gaze) when watching files.

[`npm-run-all`](https://www.npmjs.com/package/npm-run-all) is a CLI tool to run multiple npm-scripts in parallel or sequentially.

Next, we need to modify our `package.json` `"scripts"` property to watch and process `.scss` files into `.css` ones:

```json
{
  "name": "marvel-bank",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "node-sass-chokidar": "^1.3.3",
    "npm-run-all": "^4.1.3",
    "react": "^16.4.1",
    "react-dom": "^16.4.1",
    "react-scripts": "1.1.4"
  },
  "scripts": {
    "build-css": "node-sass-chokidar src/ -o src/",
    "watch-css":
      "npm run build-css && node-sass-chokidar src/ -o src/ --watch --recursive",
    "start-react": "react-scripts start",
    "start": "npm-run-all -p watch-css start-react",
    "build-react": "react-scripts build",
    "build": "npm-run-all -s build-css build-react",
    "test": "react-scripts test --env=jsdom",
    "eject": "react-scripts eject"
  }
}
```

These scripts allow us to compile `.scss` files into `.css` and to keep watching the `src` folder for changes to the content of existing `.scss` files or the addition of new ones. To complete this task, we need to change the file extension of `App.css` and `index.css` to `.scss`. Depending on our development environment, this can be done in different ways such as renaming the files or refactoring their name or file type.

Storybook will only understand changes made or applied in `.css` files. If we were to make a change in a `.scss` file, we would need to compile it into `.css` for Storybook to be notified of the styling changes.

Normally, such compilation is a build step in our development workflow triggered by running `npm start`. However, I made the promise that we wouldn't have to run our React app in order to use Storybook in this blog post. I am keeping that promise and `npm start` is off-limits. What can we use instead? `watch-css`.

As stated earlier, `watch-css` compiles our SCSS into CSS files using the `build-css` script and it keeps monitoring all the SCSS files present under the `src` directory to detect any changes. Anytime an SCSS file is changed, that file is compiled and Storybook is able to see and apply the styling changes into the component preview (as we'll see soon!).

With this in mind, on the shell run the following command:

```shell
npm run watch-css
```

This is a good point to make our first `git` commit.

## Using `git` Version Control

Our project is in a good place for its first `git` commit. But before we do so, let's ensure that we have everything we need to ignore specified in the `.gitignore` file. If you are using an IDE like WebStorm, for example, there are extra files that the IDE creates that is better to keep out of the `git` repo.

I personally like to use [`gitignore.io`](https://www.gitignore.io/) to generate the content of my `.gitignore` file automatically. The categories that I choose to create the file are WebStorm, IntelliJ, OSX, Windows, and Visual Studio Code, since they are the tools and platforms that are most commonly used. You may head to that site, enter those categories, and copy/paste the output at the end of the `.gitignore` file present in our project.

Since our `.css` files are built automatically under our project configuration, we do not need to include them in version control. In the `.gitignore` file add the following rule at the end:

```text
// .gitignore

// ...

src/**/*.css
```

This rule ensures that none of the `.css` files under the `src` folder are tracked by `git`.

With a comprehensive `.gitignore` file in place, let's initialize a `git` repository (make sure that `marvel-app` directory is the current working directory):

```shell
git init
```

Let's run a quick `git status` check to see what files are being untracked:

```shell
git status
```

Let's go ahead and add these files shown to `git` in order to include them in our commit:

```shell
git add .
```

We used a shortcut here to add all the files that were being untracked using the `.` after the `add` command.

> If you want a `git` refresher, I highly recommend this amazing [_Git & Version Control_](https://www.git-tower.com/learn/) tutorial by the folks at [Git Tower](https://www.git-tower.com/).

Running `git status` again would show us the new files that have been added that include changes to be committed. Let's create our first commit then:

```shell
git commit -m "Initial commit"
```

We'll get a reply by `git` showing all the files that were changed and the insertions that were made. Having a well-thought commit history in place will let us go back in time if we ever need to use an older version of our code. `CTRL/CMD + Z` can only go so far back!

This all looks good to me ([LGTM™](https://knowyourmeme.com/memes/lgtm)), but before we include any styling or components in our project, we need to create a sound file structure.

## Project Structure

An internal pattern that we use is to have specialized folders to hold the different elements of our React application. In one of our projects, we have the following structure:

```shell
- src
    |-- api/
    |-- features/
    |-- assets/
    |-- redux/
    |-- styles/
    |-- utils/
    |-- App.js
    |-- index.js
    |-- routes.js
```

For the initial phase of this project, we only need the `features` and the `styles` folder. The `features` folder holds our components in a categorized manner. We define features of our applications, such as `search` or `reports` in its subfolders, and create components that power and build that feature. What Storybook will help us solve is the event where features share components. Instead of duplicating the code across features, the feature will implement the component from a central source: our component library. As the name suggests, these common components go into a `common` feature folder.

This is the project structure we want for the `src` folder in this phase of the project:

```shell
- src
    |-- features/
    |---- common/
    |-- styles/
    |---- _theme.scss
    |-- App.js
    |-- App.scss
    |-- index.js
    |-- index.scss
    |-- registerServiceWorker.js
```

<include src="TweetQuote" quoteText="Instead of duplicating the component code across features in your project, implement the component from a central source, like a component library."/>

Let's go ahead and create these folders and files:

![Demo banking app file and code structure](https://images.ctfassets.net/23aumh6u8s0i/2dU4QkYNlJJVywa4N2tDLC/9a9ee8f4619c15548be4d0b9a7c1cdd8/file-structure)

We'll be using `_theme.scss` in a moment. This is a good checkpoint. Let's go ahead and commit:

```shell
git status
git add .
git commit -m "Create project structure that integrates with SCSS"
```

> Noticed something different this time? Since the `features` folder and its `common` subfolder are currently empty, they were not included as part of the commit bundle by git. We could place an `index.js` file inside `common` that exports all of the components within that folder using what is known as a [barrel export](https://medium.com/@klauskpm/do-a-barrel-export-aa5b79b76b05). For this blog post, we are not going to use that just yet.

## Creating the Application Theme

`_theme.scss` is an SCSS partial that will be imported by any other component stylesheet that needs to apply the defined theme based on the [Marvel Banking Style Guide](https://auth0.github.io/marvel-bank-styleguide/). You can copy and paste the following definitions to your local `_theme.scss` file:

```scss
// src/styles/_theme.scss

// Fonts
$primary-font: "Lato", sans-serif;
$secondary-font: "Open Sans", sans-serif;

// Font Colors
$color-text: #4f6c8d;
$color-text-light: #a3adb4;
$color-text-lighter: #ccd6e1;

$color-text-contrast: #ffffff;
$color-text-contrast-light: #a7b5c6;
$color-text-contrast-lighter: #5f5f63;

// Background Colors
$gray: #bec9d1;

// Primary Colors
$blue: #506e8d;
$white: #ffffff;
$green: #6bbfab;
$red: #f96b6b;

// Dark Primary Colors
$dark-blue: #33475c;
$dark-white: #f0f0f0;
$dark-green: #5ba392;
$dark-red: #de5e5e;

// Auxiliary Colors
$bright-blue: #5db8eb;
$opaque-blue: #4770d6;
$opaque-yellow: #f3c416;
$opaque-red: #dd765f;
```

Since this is a significant checkpoint, let's commit again:

```shell
git status
git add .
git commit -m "Create app theme variables"
```

It's time to start creating components!

## Creating A Reusable Button Using React

To see the benefits and value that Storybook provides us, we need to have components to visualize. Right now, we have none.

Recall that the Marvel UI Kit offers us the definition of a button that has three presentations:

![Styling UI buttons - Primary, secondary, tertiary - Active and Disabled state buttons](https://images.ctfassets.net/23aumh6u8s0i/6i3Qy1NxBCFUJaAwuXyTuj/31b7a71ce3de1fd752c0f908f8061fda/ui-button)

These presentations can be summarized as follows:

- Active State (Fill): The button is green, pops up, and has white text.
- Active State (No-Fill): The button shares the background of the parent container, and it has a blue color for its text and border.
- Disabled State: The button looks suppressed and has a light blue color for its text and border.

The button itself has two status: active or disabled. The relationship between presentation and state is something that we can express easily with Storybook. First, we need to plan the component. How are we going to approach its engineering?

Let's start with creating the basic structure of the component: a rounded rectangle that contains a label. Create a file named `Button.js` under the `common` folder and populate it with this:

```javascript
// src/features/common/Button.js

import React from "react";

const Button = props => <div>{props.label}</div>;

export default Button;
```

Let's quickly commit the creation of the `Button` component:

```shell
git status
git add .
git commit -m "Create Button component"
```

Now that we have a component, we go back to one of the questions that we have been asking ourselves in our team when creating components:

- How should a prototype of the component be presented? Should a blank page with mock data be used?

Traditionally, we would compose the component into a visible element of the UI to preview it. This time, we are going to use Storybook.

### Next Steps

We have built a foundation to help us create our online banking web app with consistent branding by implementing a style guide. At Auth0, different teams are making extensive use of Storybook as a development and design tool. We are converging designers and developers into a Design Systems team that is letting us iterate faster and develop better products for our cherished customers.

Feel free to grab the source code of the project we have created so far from the [Marvel Bank App GitHub repo](https://github.com/auth0-blog/marvel-bank-app). The repo is being built gradually and contains commits that cover the work we have done in this blog post and on future posts. To start from scratch, be sure to [create a branch from the first commit](https://stackoverflow.com/questions/2816715/branch-from-a-previous-commit-using-git): `Initial commit`.

For more content like this, follow [@auth0 on Twitter](https://twitter.com/auth0) or subscribe to our newsletter.

<include src="asides/AboutAuth0" />


Setting Up a Component Library with React and Storybook

Create modular and reusable components that can be shared across projects by building a component library with React and Storybook.



At Auth0, we want our customers to be successful using our [authentication solutions](https://auth0.com/b2c-customer-identity-management). The Customer Success Infrastructure Team builds customer-facing and internal tools that help us achieve that goal. One of the technologies that have enabled them to have rapid iterations in user interface development is [React](https://auth0.com/blog/react-tutorial-building-and-securing-your-first-app/).

[![Authenticate React using Auth0](https://images.ctfassets.net/23aumh6u8s0i/6I21NcoVBzBDHBnSxXfaZw/49c51ce5e8389783b607cd5312811480/react-auth0-banner)](https://auth0.com/authenticate/react/)

This team builds a variety of different projects such as the software that runs our [Auth0 Support Center](https://support.auth0.com/) and other internal tools that power internal support workflows. In addition to React, they develop their projects using [Node.js](https://nodejs.org/en/), [hapi.js](https://hapijs.com/), and [Redux](https://redux.js.org/). It is a JavaScript-heavy team and that is driven by building quality features quickly.

![Auth0 Customer Success Infrastructure Team](https://images.ctfassets.net/23aumh6u8s0i/1TZtO3xXdNrGdS2nshJank/3ab11dc08159450bbd3af27ae27d3785/auth0-customer-success-team)

> Would you like to be part of a Team like this? We are currently hiring engineers to [join the Customer Success Infrastructure team](https://auth0.com/careers/positions?areas=Customer%20Success)!

[Guillermo Rodas](https://twitter.com/glrodasz) is one of the Engineers of the Customer Success Infrastructure Team. He recently led a project initiative known as _Support Center Components_ that solved a problem centered around having duplicate React components in our customer-facing and internal tools site.

In this blog post, through Guillermo's insight, we are going to explore how the Account Center Team is using [React and Storybook](https://storybook.js.org/basics/guide-react/) to optimize UI development and promote consistent branding by creating a component library that can be shared across different projects.

## Don't Repeat Yourself (DRY)

[Auth0 Support Center](https://support.auth0.com/), a customer-facing site, and Customer Success Tools, an internal site, have similar elements on their interfaces. For example, despite having a different business context in each interface, the _Quota Utilization_ feature in both interfaces uses the same structure to report data to the user.

![Two identical React component defined in different codebases](https://images.ctfassets.net/23aumh6u8s0i/1lutGPjqyYNHccPBpXxf3z/ba96df5eb6edb898634676ced807c5ad/support-center-vs-cs-tools-component)

The problem that we had was that this structure was being implemented as a React component separately for each interface instead of sharing the implementation. The development team was duplicating components to solve the same problem. This approach inherently created pain points for developers as _Quota Utilization_ was just one of a few other features that had overlapping front-end architectures within our sites.

Having duplicate code is not ideal. One version of the code may be more up-to-date than another version, creating something similar to a race condition around code versioning. If a bug is found, it would need to be fixed in every place that shares the code while [hoping that the developer can remember them all](https://stackoverflow.com/a/2490897). An inconsistent bug fixing process could multiply bugs and create havoc in a codebase.

> "If you see patterns in your code, that is an [indication it is prime for DRYing](https://americanexpress.io/clean-code-dirty-code/). Sometimes this means standing back from the screen until you can’t read the text and literally looking for patterns." [(Donavon West, American Express Developer Relations)](https://twitter.com/donavon)

The solution for this code duplication problem was to make the code DRY (Don't Repeat Yourself). We needed to write the presentational component once and then have each feature/interface implement it from a single source of truth: a component library.

As explained by [Mark Perkins](https://twitter.com/allmarkedupa) from [Clearleft](https://clearleft.com/) on their insightful post [_On Building Component Libraries_](https://clearleft.com/posts/on-building-component-libraries), a component library is an effective and robust format for delivering documented code and design patterns to developers and clients. React lends itself to the architecting of a component library since it involves the process of thinking and building in a "componentised manner", as coined by Mark.

<include src="TweetQuote" quoteText='react lends itself to the architecting of a component library since it involves the process of thinking and building in a "componentised manner", as coined by @allmarkedup from @clearleft'/>

![Graphic of example web component library](https://images.ctfassets.net/23aumh6u8s0i/7b4rPdBjXGdnxv24ty2Vzc/7aa292937b5eb827ea725d4010561686/component-library)

[Source](https://blog.hichroma.com/beyond-bootstrap-moving-from-ui-toolkit-to-component-library-f0a34f05e98b)

## Integrating a Component Library

Implementing the concept of a component library within our workflow was an architectural decision that required us to further strategize our component and feature development process.

For example, when creating a component, we started asking the following questions:

- How to categorize the component within a library? Should we have categories at all?
- How should a prototype of the component be presented? Should a blank page with mock data be used?
- Should different states of the component be presented on its prototype?

It was critical to be able to answer these questions visually and in an organized manner to help us iterate cleanly through our feature development process. This process typically consists of:

- Creating an MVP (Minimum Viable Product) or POC (Proof of Concept).
- Getting feedback on the MVP/POC.
- Integrating feedback through development iterations.

Through that process, we are constantly showing how the user interface presents data through its components and defining the states of a component based on the data that it can present. We needed a tool that could let us:

- Create our components independent from any specific feature integration.
- Preview our components and their different states.
- Let us categorize each component into families for easier lookup.
- Host our components in a central location to create the concept of a library.

With React, we could already define components. We needed something to preview, categorize, and host them. Fortunately, we were able to fulfill all those requirements using one single tool: Storybook.

<include src="TweetQuote" quoteText="Don't reinvent the  &lt;Wheel /&gt;. To create modular and reusable components that can be shared across projects, build a component library with React and Storybook."/>

![Meme - I believe in code reuse... CTRL-C, CTRL-V](https://images.ctfassets.net/23aumh6u8s0i/2J67xmm28v3y1IGGkdHtmh/094c27a7ffdb0f2ff51d89c771ad3184/believe-in-code-reuse)

[Source](https://hermesespinola.wordpress.com/2016/11/24/code-reusability-dont-reinvent-the-wheel/)

## Storybook: Let Your Components Tell a Story

[Storybook](https://storybook.js.org/) is a UI development environment for UI components. It acts as a board where we can stage our components and visualize them in different states and interact with them as if they were on a live application. This is all done in isolation since Storybook runs outside of our app. Storybook has its own Webpack setup that is very similar to the one from `create-react-app` but can be configured to meet our needs. The platform also comes with a built-in dev server to help us preview our components locally.

![React Storybook component preview](https://images.ctfassets.net/23aumh6u8s0i/7aBehDlHBJczkWVH02PVSd/1449412c3d8c1e9ddc70e599c539c864/storybook-demo)

As we have described, we already had a working project when we decided to use Storybook to create a component library. However, because of its independent architecture, adding Storybook to our existing project did not create any burden or changes to our existing codebase.

We added it like any other `npm` package and then imported our existing components into its platform. However, it did require us to think differently about the creation, maintenance, and sustainment of our components moving forward &mdash; an integrative process we call "storybook-driven development."

With Storybook, we have been able to build our React components gradually in isolation without having to worry about having the final component version or environment ready from the start. It has doubled as a staging and planning tool for us.

<include src="TweetQuote" quoteText="Storybook and React let us plan, stage, and build components gradually. It's a living style guide."/>

## Documenting and Testing Pain Points

Our Customer Success Infrastructure team had a second problem: documenting and testing all the different scenarios of each project feature. In our projects, we have tests with high coverage that are run through a [continuous integration pipeline configured in Heroku](https://devcenter.heroku.com/articles/heroku-ci).

In Guillermo's words:

> "We have strong tests along with continuous integration because we want to have nice weekends without worrying about our production builds failing. The most common phrase in a [Pull Request (PR)](https://help.github.com/articles/about-pull-requests/) is: Please add the tests."

Aside from testing, we place high value in documenting code. It's our legacy for anyone who will be working with our codebase in the future. Fortunately, having a component library like Storybook allows us to document components visually and declaratively. Storybook provides a developer with all the information needed to understand the structure and state of a component.

Testing is hard. For most developers, testing is a sad story. Well, not anymore! With modern and powerful tools, our testing story is a happy one.

In React, there are different aspects of UI Testing. We categorize them as follows along with their tooling:

- Structural Testing:
  - [Enzyme](https://github.com/airbnb/enzyme)
  - [Jest Snapshot Testing](https://jestjs.io/docs/en/snapshot-testing)
- Interaction Testing:
  - Enzyme
- CSS/Styles Testing:
  - Image comparison to do regression testing
  - Jest Snapshot using inline styles
  - Other tools like [BackstopJS](https://garris.github.io/BackstopJS/), [PhantomCSS](https://github.com/HuddleEng/PhantomCSS), [Gemini](https://gemini-testing.github.io/), and [Happo](https://github.com/Galooshi/happo)
- Manual Testing

Storybook integrates with Jest Snapshot through an add-on called [`StoryShots`](https://github.com/storybooks/storybook/tree/master/addons/storyshots/storyshots-core). `StoryShots` adds automatic Jest Snapshot Testing to our codebase by using our existing Storybook stories as the input for Jest Snapshot Testing.

With our Heroku CI pipeline configured, each time someone makes a PR with a new component against our Storybook, this automated testing is triggered and a visual preview of our app is created. This lets us perform structural and style testing much faster.

## Sharing our Engineering Knowledge

We are happy to share what our engineering process looks like in detail and how it has positively impacted our developer experience in creating, testing, and documenting user interfaces.

You may stay in touch with us by following [@auth0 on Twitter](https://twitter.com/auth0), subscribing to our newsletter, or checking this blog back from time to time. We hope that you'll love the content that we are creating.

<include src="asides/AboutAuth0" />
