Storybook 5.0

Storybook is an environment for developing interactive component libraries for the most popular frontend frameworks, such as React. JS Consulting, Angular and Vue. It allows everybody who's participating in a project, including designers, developers and even the customer, to interact with the designed components. Designers can see how their designs come to life, developers can use the component library as a source for creating views on the frontend and if shared with the customer, they can see the building blocks of their product(s). Many big companies, such as Google, Shopify and Salesforce have design systems that include a library of reusable components for achieving an unified look and feel in their products.

The created Storybook should be used as a “single source of truth” for the frontend development related matters. Everytime a developer creates a new reusable component such as a button component for example, it should be added to the Storybook with the most common use case examples. For example for an input component, the stories (a story is a single component represented in Storybook) might display a small, medium and a large input field with different states such as error, invalid or valid. Adding each component to the Storybook is immensely helpful for other frontend developers now and in the future as the whole documented frontend component library can be seen at a quick glance instead of manually going through the codebase, trying to figure out how to use each component. The created Storybook can be exported as a static app and shared online so all the other interested parties can use it as well.

Storybook 5.0 was released in the beginning of March and it comes with an improved new user interface that provides even better developer experience than before. It also has a new Theming API and an expanded addons API for customising your Storybook even further:

Getting started

Storybook can be included in your existing React project pretty easily. In this example I'm using a create-react-app based project, but with little changes any React project would do. In the root of your project folder, all you need to do is to run npx -p @storybook/cli sb init and Storybook will figure out the configuration based on your package.json file. The script will install required dependencies, add related scripts to package.json and add a .storybook folder containing Storybook's configuration files. It'll also add a stories folder to your project (placement depends on your own project setup). After the script has finished running, run npm run storybook or yarn storybook to start it. Storybook also uses Webpack-dev-server inside to run the Storybook that has hot module reloading enabled, so you'll see the changes you make pretty much instantly. Pretty neat, eh?

Configuration

Storybook allows the user to extend its Webpack configuration with standard webpack plugins so that additional features such Typescript or SCSS can be used. To enable this behaviour, add a .storybook/webpack.config.js file exporting a Webpack configuration as an object or a function. Storybook has something called "Extend" and "Full Control" modes for the custom Webpack configuration, Extend mode merges the exported object to Storybooks own default Webpack configuration and Full Control mode allows the end user to configure all aspects of the Webpack configuration via passed in function parameters.

By default, Storybook looks for stories from a single folder that is defined in .storybook/config.js. In my opinion, a better pattern is to add a "story" beside each component in their respective folders so that everything related to that single component is in one place. So if you had a /Forms/CustomInput/index.jsx file, you'd add a /Forms/CustomInput/CustomInput.stories.jsx (or similar) file in the same folder. To make Storybook find stories from multiple places within your project, add some Webpack black magic to the .storybook/config.js file and your good to go:

import { configure } from ‘@storybook/react’; 
const req = require.context('../src', true, /.stories.jsx?/); 
function loadStories() { req.keys().forEach(filename => req(filename)); } 
configure(loadStories, module);

Addons

Storybook also has a concept of addons that can be used to extend the behavior of the component library. There are lots of addons available in the Addon page on Storybook's website. One good example addon to try out is called Knobs which lets you edit components props dynamically from the Storybook application panel. For example for an input component, you might want to see how it behaves when it is in different states (valid, invalid, error) or for a button component you might want to see what happens when the button is disabled or enabled. To include an addon in your Storybook, first install it (npm install @storybook/addon-knobs --save-dev) or yarn add @storybook/addon-knobs -D and then import and configure it in your .storybook/addons.js. More specific instructions can be found in each addons readme.

Writing stories

Writing stories is fairly straightforward as well. Each story begins with a storiesOf function call that has a name for the story which is displayed on the left side menu in your Storybook. To create nested stories, include a path with forward slashes in the function call such as storiesOf(‘Forms/CustomInput’, module). To add components to a story, call the add function on the storiesOf return value. You can also add something called decorators, which basically are wrappers for your stories providing additional functionality. Among stories, in the example below I am adding a decorator that center each component in the Storybook view.

// ./Forms/CustomInput/CustomInput.stories.jsx
import React from "react";
import { storiesOf } from "@storybook/react";
import CustomInputField from '../CustomInputField;

storiesOf(‘Forms/CustomInputField, module)
 .addDecorator(story => (
 <div
 style=
 >
 {story()}
 </div>
 ))
 .add('default', () => (
 <CustomInputField placeholder="Default!" />
 ))
 .add(‘valid’, () => (
 <CustomInputField placeholder="Valid!" dirty={true} error="" />
 ))
 .add(‘invalid’, () => (
 <CustomInputField 
 placeholder="Error!" 
 dirty={true} 
 error=”This field is required”/>
 ));

Recap

I think UI development environments such as Storybook are a good addition to software development projects. Having a unified single source of truth for the components is valuable for both developers and designers, and setting one up isn't too hard either as we just saw as the team behind Storybook has made getting started with it really easy. Check out Storybook’s documentation and the official Storybook React live example for more examples.