DEV Community: Thibaud Ducasse

How to use Storybook with React

Thibaud Ducasse — Thu, 20 Jun 2019 14:49:25 +0000

Streamline your UI component development workflow

What is Storybook and why would I use it?

Storybook is an open source tool for developing UI components in isolation

Reusable components

React allows us to write what we call "reusable components". If you don't know what a reusable component is, think about buttons for example:

you can have different variants:
- a primary button with a red background
- a secondary button with a green background
you can also have different states: a button can be disabled if the form is currently being sent

In React, a very simple way to handle it is to have a single Button component which takes different parameters:

a prop called disabled, which is either true or false
a prop called variant, which is either primary or secondary.

But let's say you are writing this code and you want to see what it looks like. The usual approach would be to go to a page in your application, then include the button somewhere in the middle, pass props to it, and see what it looks like.

Comes Storybook

That's where Storybook comes into play: it basically allows you to run a second app in parallel, where you can play with the Button component, without having to include it in your application. You can develop your components in isolation.

Now, let's say someone in support team is talking to a customer that can't login. They come to you and ask: "Hey, could you show me this error screen?".

Without Storybook, the answer involves having to launch the application, try to replay what the user did, read some code to understand how to make it appear, etc.

With Storybook, you just type "Error Screen" in the search bar, and you instantly see it!

Set up Storybook in a React app

At this point you will need a React application. If you don't have one, feel free to clone this one, or follow the steps in this post to create one. This tutorial will assume that you use create-react-app.

Storybook makes it really easy to set everything up. In your terminal, just run:

npx -p @storybook/cli sb init

This will basically inspect your package.json to determine the framework you are using, then generate the right configuration for your project.

The command should have updated your package.json scripts, adding:

"storybook": "start-storybook -p 9009 -s public",
"build-storybook": "build-storybook -s public"

The first one is the one we are interested in. Run:

npm run storybook

This should open something like this in your browser (if it doesn't, just navigate to localhost:9009):

Let's have a look at the interface here:

on the left, a sidebar: this is where you find your components. Click on Button, and look at what's there!
at the bottom, something that looks like a console: this is actually the "addons" section. Storybook has a lot of addons, which allow you to enhance your experience while developing your components: change props dynamically with, log outputs, switch languages, etc.

So where do these components come from? When we installed Storybook, it generated these "demo" stories. They are in src/stories/index.js:

import React from "react";

import { storiesOf } from "@storybook/react";
import { action } from "@storybook/addon-actions";
import { linkTo } from "@storybook/addon-links";
// Importing the demo components from storybook itself
import { Button, Welcome } from "@storybook/react/demo";

storiesOf("Welcome", module).add("to Storybook", () => (
  <Welcome showApp={linkTo("Button")} />
));

storiesOf("Button", module)
  .add("with text", () => (
    <Button onClick={action("clicked")}>Hello Button</Button>
  ))
  .add("with some emoji", () => (
    <Button onClick={action("clicked")}>
      <span role="img" aria-label="so cool">
        😀 😎 👍 💯
      </span>
    </Button>
  ));

The magic that adds them to Storybook is in .storybook/config.js:

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

function loadStories() {
  require('../src/stories');
}

configure(loadStories, module);

Write your first stories

Configuring Storybook

The first thing we need to do is to get rid of these demo stories, and change the way stories get included in Storybook. Remove the src/stories/ folder altogether, we won't need it.

Replace everything in .storybook/config.js with:

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

const req = require.context('../src/', true, /\.stories\.js$/);

function loadStories() {
  req.keys().forEach(filename => req(filename));
}

configure(loadStories, module);

This will tell Storybook to pick up every file that ends with .stories.js. You'll see that it's (in general) much easier to keep stories close to the components they test.

A simple Button component

Now let's write our first story. If you are using my github example, go to src/components/atoms and create the following files:

|––atoms
  |––Button
    |––index.js
    |––Button.js
    |––Button.stories.js

Button.js:

import React from "react";

const Button = props => {
  const { variant, disabled, children } = props;

  // This is the default style
  let backgroundColor = "white";
  let color = "black";

  // Which variant do we want?
  switch (variant) {
    case "primary":
      backgroundColor = "red";
      color = "white";
      break;
    case "secondary":
      backgroundColor = "green";
      color = "white";
      break;
    default:
      break;
  }

  // Let's build the style based on the variant
  // We also add properties depending on the `disabled` state
  const style = {
    backgroundColor,
    color,
    cursor: disabled ? "not-allowed" : "pointer",
    opacity: disabled ? 0.5 : 1
  };

  return (
    <button disabled={disabled} style={style}>
      {children}
    </button>
  );
};

export default Button;

Button.stories.js:

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

// You can see this as "folders" in Storybook's sidebar
const stories = storiesOf("atoms/Button", module);

// Every story represents a state for our Button component
stories.add("default", () => <Button>Button</Button>);
stories.add("default disabled", () => <Button disabled>Button</Button>);
stories.add("primary", () => <Button variant="primary">Button</Button>);
// Passing a prop without a value is basically the same as passing `true`
stories.add("primary disabled", () => (
  <Button variant="primary" disabled>
    Button
  </Button>
));
stories.add("secondary", () => <Button variant="secondary">Button</Button>);
stories.add("secondary disabled", () => (
  <Button variant="secondary" disabled>
    Button
  </Button>
));

index.js:

// This allows us to import `src/components/Button` directly,
// without having to go all the way to `src/components/Button/Button`
export { default } from "./Button";

Now go to Storybook again, and have a look at what your story created:

Go through the different stories we've created, and notice how the Button changes.

Everything is real-time

Storybook has a very fast hot reload mechanism. This means that you can go to your component, change "red" into blue, and Storybook instantly re-compiles your stories to include your change!

Addons

Storybook provides various very convenient addons to help us develop components in isolation with confidence. Let's set up some of them.

addon-info

Sometimes when you browse through Storybook, you want to read the code for a specific story. This is exactly what the info addon does. To install it:

npm i -D @storybook/addon-info

Add the plugin globally, by editing .storybook/config.js:

...
import { addDecorator } from '@storybook/react';
import { withInfo } from '@storybook/addon-info';

addDecorator(withInfo);
...

This will add a show info button in the top right hand corner in your story, which displays some information about the story:

addon-actions

It can be useful to log when an action happens in our component. Let's say for example that we change our Button component so that it accepts an onClick prop:

...
const Button = props => {
  const { variant, disabled, children, onClick } = props;
  ...
return (
    <button onClick={onClick} disabled={disabled} style={style}>
      {children}
    </button>
  );

How do we test that clicking the button will trigger the onClick handler? Storybook provides an official addon, already installed, that can help with that. In your story, import action, then add the onClick prop:

import { action } from "@storybook/addon-actions";
...
stories.add("default", () => (
  <Button onClick={action("clicked!")}>Button</Button>
));
stories.add("default disabled", () => (
  <Button onClick={action("clicked!")} disabled>
    Button
  </Button>
));
stories.add("primary", () => (
  <Button onClick={action("clicked!")} variant="primary">
    Button
  </Button>
));
stories.add("primary disabled", () => (
  <Button onClick={action("clicked!")} variant="primary" disabled>
    Button
  </Button>
));
stories.add("secondary", () => (
  <Button onClick={action("clicked!")} variant="secondary">
    Button
  </Button>
));
stories.add("secondary disabled", () => (
  <Button onClick={action("clicked!")} variant="secondary" disabled>
    Button
  </Button>
));

Now, every time you click the button, Storybook will print a new log:

addon-knobs

Right now, we need to write a lot of different stories for the same component, because we need to handle every prop combination. What if we could edit the props in real-time, in Storybook itself? The solution is addon-knobs, and it greatly simplifies the way we write stories.

First, install the addon with:

npm i -D @storybook/addon-knobs

Then, add this to .storybook/addons.js:

import '@storybook/addon-actions/register';
import '@storybook/addon-links/register';
// add this line
import '@storybook/addon-knobs/register';

And rewrite your story to use the new plugin:

import React from "react";
import { storiesOf } from "@storybook/react";
import Button from "./Button";
import { action } from "@storybook/addon-actions";
// add this line
import { withKnobs, select, boolean } from "@storybook/addon-knobs";

// You can see this as "folders" in Storybook's sidebar
const stories = storiesOf("atoms/Button", module);

// add this line
stories.addDecorator(withKnobs);

// ---- add this block
const variantOptions = {
  none: "",
  primary: "primary",
  secondary: "secondary"
};
// ----

stories.add("with knobs", () => (
  <Button
    onClick={action("clicked!")}
    // ---- and this one
    // syntax is (name, options, default)
    variant={select("variant", variantOptions, "")}
    // syntax is (name, default)
    disabled={boolean("disabled", false)}
    // ----
  >
    Button
  </Button>
));

Now, when you go to your story, in the addons section, you can see a new tab, called knobs, and you can change theh props for your component by playing with them:

What's even cooler is that addon-info is kept in sync with these props!

Snapshot testing

Since React components are reusable, it's very common that a component gets included in many other components. Keeping track of all the places where the component becomes a dependency and estimating the impact of a small change can become very difficult. Storybook makes it very easy to set up snapshot tests, combined with jest (create-react-app already comes with it).

First, install the required dependencies:

npm i -D @storybook/addon-storyshots react-test-renderer require-context.macro

Then, in .storybook/config.js:

import requireContext from 'require-context.macro';

// const req = require.context('../src', true, /\.stories\.js$/); <-- replaced
const req = requireContext('../src', true, /\.stories\.js$/);

Create the following structure in src:

|––test
  |––storyshots.test.js

And add this to storyshots.test.js

import initStoryshots from '@storybook/addon-storyshots';

initStoryshots();

Finally, run npm run test (or the npm test shorthand). This will create a snapshot file at src/test/__snapshots__/storyshots.test.js.snap.

Now, when you run the tests, Storybook will render every story and compare it to the snapshots created earlier. Try to change something in your Button component and run the tests again, for example:

switch (variant) {
    case "primary":
      backgroundColor = "red";
      color = "white";
      break;
    case "secondary":
      // change this...
      //backgroundColor = "green";
      // ...into this
      backgroundColor = "gray";
      color = "white";
      break;
    default:
      break;
  }

Jest will complain that the snapshots are not right, and give you a very useful report:

You can review the changes, and decide if you have broken something or if every change was intended. If everything looks OK, you can update the snapshots, using:

npm run test -- -u

Running snapshot tests after developing a big feature can be very helpful to review what you have done and the impact of your changes.

Find the final code on GitHub.

Create-react-app with VS Code

Thibaud Ducasse — Thu, 20 Jun 2019 14:49:18 +0000

Set up a basic React development environment using create-react-app and VS Code

Requirements

Note: I uploaded the final code on GitHub.

Create a new project using create-react-app

create-react-app provides a very easy way to generate a React app in seconds. This is currently developed by Facebook, and the recommended way to start a new project.
Open a terminal and go to the desired folder (create-react-app will create a folder for your app).

cd ~/Projects # this is my projects folder
npx create-react-app my-app # replace `my-app` with the name of your app
cd myapp
npm start

You should see something like this:

Folder structure

The script will generate a few files, and it should look something like this:

Let's have a look at what's been created:

package.json: This file is related to npm. It holds our dependencies (the libraries you want to be able to use in your code). You can also describe your application, add useful scripts in order to automate common tasks, such as running tests, starting a server, deploying, etc.
package-lock.json: This is auto-generated by npm every time you add a new dependency. You should never have to touch it, and it is good practice to commit it to your repository.
.gitignore: When you commit files to a git repository, git will (by default) want to add every file that's in your project. But sometimes you might want to exclude a file, and .gitignore is exactlly that. By default, create-react-app excludes node_modules for example, which is the folder containing all our dependencies. Since we are going to commit package.json and package-lock.json anyway, there is no need at all to commit them (plus they are super heavy).
public folder: This is where we find the root of our application, index.html, and our favicon, favicon.ico.
src folder: Our app folder. This is where our code lives, and where we are going to spend 98% of our time.

Let's have a look at the code

First, let's go to index.html, and have a look at this line:

...
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
// the next line
    <div id="root"></div>

...

This will be the HTML element to which the React application will be attached.

index.js is the first file that will be loaded in our application.

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import * as serviceWorker from './serviceWorker';

// the next line
ReactDOM.render(<App />, document.getElementById('root'));

This line is the one that actually links our React app to the DOM (root node, as we've seen just before).

// the two next lines
import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import * as serviceWorker from './serviceWorker';

ReactDOM.render(<App />, document.getElementById('root'));

These two first lines are everything that's necessary to write React code.

import React from 'react';
import ReactDOM from 'react-dom';
// the two next lines
import './index.css';
import App from './App';
import * as serviceWorker from './serviceWorker';

ReactDOM.render(<App />, document.getElementById('root'));

These ones are just importing our React components (here App), and our CSS files.

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
// the next line
import * as serviceWorker from './serviceWorker';

ReactDOM.render(<App />, document.getElementById('root'));

This last line is used only if you are writing a PWA (Progressive Web App, more on this here). Yes, create-react-app is already configured as a PWA!

So what is this App.js doing? Let's have a look:

import React from 'react';
import logo from './logo.svg';
import './App.css';

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>
          Edit <code>src/App.js</code> and save to reload.
        </p>
        <a
          className="App-link"
          href="https://reactjs.org"
          target="_blank"
          rel="noopener noreferrer"
        >
          Learn React
        </a>
      </header>
    </div>
  );
}

export default App;

At the beginning, you can see the standard import React from 'react' that you need to include in every file that uses jsx (this cool HTML-like syntax that we use to write React components).
You may have noticed that we import a file called App.css.
Open it, and look at what's written here:

.App {
  text-align: center;
}

.App-logo {
  animation: App-logo-spin infinite 20s linear;
  height: 40vmin;
  pointer-events: none;
}

.App-header {
  background-color: #282c34;
  min-height: 100vh;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  font-size: calc(10px + 2vmin);
  color: white;
}

.App-link {
  color: #61dafb;
}

@keyframes App-logo-spin {
  from {
    transform: rotate(0deg);
  }
  to {
    transform: rotate(360deg);
  }
}

I'm not going to spend too much time on this, but let's take the example of the first class:

.App {
  text-align: center;
}

And let's see how we use it in a React component:

function App() {
  return (
    // the next line
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>
          Edit <code>src/App.js</code> and save to reload.
        </p>
        <a
          className="App-link"
          href="https://reactjs.org"
          target="_blank"
          rel="noopener noreferrer"
        >
          Learn React
        </a>
      </header>
    </div>
  );
}

As you can see, the main difference with "normal" HTML is that the name of the attribute is className, instead of class.

Configuring VS Code

Enough about create-react-app and the code it generated, it's time to configure our code editor.
VS Code has pretty good defaults (syntax highlighting, autocompletion, 'go to definition', etc). But you can make it even better!

ESlint

Since JavaScript is not a compiled language, there is nothing that can tell us if something looks like it's going to fail before we actually run it. ESLint solves exactly this problem.

ESLint is the most popular JavaScript linter. A linter is a program that analyses your code, and tries to find potential errors, ahead of runtime. ESLint is highly configurable, and you can extend premade sets of rules, define your own rules, override existing rules, etc.

Luckily, create-react-app already comes with ESlint. So we don't have much to do!

Install the ESLint extension for VS Code. This will allow us to see the result of ESLint directly in VS Code.

Once installed, you can quickly test it. Go to App.js again, and remove this line:

<a
    className="App-link"
    href="https://reactjs.org"
    target="_blank"
    // the next line
    rel="noopener noreferrer"
  >

VS Code should start yelling at you:

Prettier

Prettier is an opinionated code formatter. People used to fight for hours around commas, semi-colons, etc. Prettier is an attempt at ending the debate. Since most editors have a Prettier plugin, you can "autoformat on save", which means you can write ugly code, and never worry about formatting!

You can use Prettier in different ways. My favorite one is to run it as part of the ESLint rules.

First, install the Prettier dependencies:

npm i -D prettier eslint-config-prettier eslint-plugin-prettier

Then, create a file, at the root of your app, called .eslintrc.json as such:

{
  "extends": [
    "react-app",
    "prettier",
    "prettier/react"
  ],
  "plugins": [
    "prettier"
  ],
  "rules": {
    "prettier/prettier": "error"
  }
}

So what have we done?

eslint-config-prettier is a package that allows us to disable the rules that would conflict with the rules defined by Prettier.
eslint-plugin-prettier is the one that allows to run Prettier as an ESLint rule.

If you have a look at the .eslintrc.json file that we just created, you'll notice that we have added a rule that basically says "everything that Prettier reports should be treated as an error".

Once everything is saved, go back to App.js and have a look at what ESLint is saying now:

Autoformatting

So this is all good, now we see what's wrong about our code, but wouldn't it be nice if we could just fix everything automatically? Replacing double quotes with single quotes should be pretty straightforward for a computer, right?

ESLint has an option to autofix every error that can be autofixed. On the command-line, it's --fix, and you can configure your VS Code so that this happens everytime you save.

Create a new folder, at the root of your app, called .vscode, and inside this folder, a file called settings.json:

{
  "eslint.autoFixOnSave": true
}

Go back to App.js, and try saving your file now, it should get reformatted instantly!

Precommit hook

So now that we have linting and formatting all sorted, what happens if someone decides to contribute to our code without setting up everything we just set up? It will break everything, and you will be back to coding-style hell. So what can we do about it?

Two packages will help us with that:

husky gives us a really easy way to set up git hooks.
lint-staged will lint the files that are ready to be committed.

First, install them with:

npm i -D lint-staged husky

Go to your package.json and add:

"lint-staged": {
    "**/*.js": [
      "eslint --fix",
      "git add"
    ]
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  }

And you're done! Now, every time you will try to commit unformatted files, husky will launch lint-staged, which will intercept the process and run ESLint first. And if there's an error ESLint can't fix, it will stop the whole process. Which means you can't commit code that doesn't work anymore!

Absolute imports

It is very common in a React project to organise your code in multiple nested folders.

Let's say we decide to implement something like Brad Frost's atomic design for example. A common way to implement it would be (this example is on GitHub):

App.js would import the LoginPage template like this:

import React from "react";
// the next line
import LoginPage from "./components/templates/LoginPage";

function App() {
  return (
    <div style={{ padding: 20 }}>
      <LoginPage />
    </div>
  );
}

export default App;

This is all good! But now, if you go to LoginPage.js, and have a look at how we have to import LoginPassword:

import React, { useState } from "react";
// the next line
import LoginPassword from "../organisms/LoginPassword";

const LoginPage = props => {
  return (
    <>
      <LoginPassword />
    </>
  );
};

export default LoginPage;

Notice the ../ to go up a folder? This will become really hard to follow once we start deeply nesting folders and files.

A good solution for that is something called absolute imports. At the root of your app, create a file called jsconfig.json:

{
  "compilerOptions": {
    "baseUrl": "./src/"
  },
  "include": [
    "src"
  ]
}

Now you can import your files using an absolute path, starting from ./src/:

import React from "react";
// the next line
import LoginPassword from "components/organisms/LoginPassword";

const LoginPage = () => {
  return (
    <>
      <LoginPassword />
    </>
  );
};

export default LoginPage;

While it might not seem like a big deal right now, because we only have one level of nesting, big applications tend to have very deeply nested components, which makes imports look like ../../../../MyComponentFolder/MyComponent very quickly!

Find the final code on GitHub.