Pic Courtesy — Google Images

Creating application catalogue using Storybook with React

Storybook + React

Note — This blog was created when the storybook 5.1.11 was the latest version. After 5.3.x version, one of the change is on configuration which is instead of maintaining individual configs under .storybook folder like config.js, addons.js, etc , creating single file main.js which defines all this configurations. Explained below when we go over the configurations.

Quick Overview -

React A JavaScript library for building the user interface. Read more at — https://reactjs.org/

Storybook -

What — It is an open source tool for developing UI components in isolation for React, Vue, and Angular. It makes building stunning UIs organized and efficient. Read more at https://storybook.js.org/.
In a nutshell, we can say it is a kind of product catalogue which shows look and feel of small components or a complete screen used in this product with standard guidelines like style guides etc. It is same as a product catalogue(or user manual), which you see in original stores while shopping e.g jewellery, paints etc

Why — There are couple of benefits like -
. Building components in isolation — As this runs in different port altogether, components can be build in isolation and shared across all over the team
. Handle tricky usecase — Render components in key states that are tricky to reproduce in an actual application.
. Document use cases as stories — As this is a collection of stories only, we can document all the usecases, screens etc.

How —

1)Lets quickly create a react app using create-react-app( boiler plate provided by Facebook itself )-

create-react-app storybook-react-demo

2)Install Storybook for react

npm i -S @storybook/react

3)To show how storybook works, I am installing reactstrap(i.e. React version of Bootstrap 4) so that we can quickly use its buttons, tables, layout components for writing stories.

npm i -S reactstrap
npm i -S bootstrap // for getting styling of its components

4) Create a script for running storybook in package.json

storybook :”start-storybook”

5)Lets create a configuration file for storybook in .storybook/config.js — We can change the config file location and its name but by default while running it takes it from here.

import {configure,addParameters} from "@storybook/react"
const req = require.context('../src/stories', true, /\.stories\.js$/);
function loadStories() {
   req.keys().forEach(filename => req(filename));
}
addParameters({ options: { showAddonPanel: false } });
configure(loadStories,module);

So basically above code is to inform storybook from where it needs to read the story with some additional configurations.

Storybook uses Webpack’s require.context to load modules dynamically from a specific path.It allows you to pass in a directory to search, a flag indicating whether sub-directories should be searched too, and a regular expression to match files against. Read more at https://webpack.js.org/guides/dependency-management/#require-context

Through addParamerters method we can add additional configuration like I did to hide the Addon Panel

Note — After version 5.3.x no need to create config.js or other files, instead of that create only one file main.js and mention all those configuration inside that. Say for above file config.js we will write it as below in main.js

module.exports = {
   stories: [‘../src/stories/*.stories.js’],
};

6)Now lets create a story inside the src/stories folder as we mentioned the path in the above config file

Basic snippet of the story

import React from “react”
import {storiesOf} from “@storybook/react”
storiesOf(“Story group name”,module)
.add(“Story name”,Function return React component)

module to enable hot replacement mdoule behavior(i.e. you don’t need to refresh the browser after every change, browser will automatically get refreshed)

Now if you go through this Github repository https://github.com/harshmons/storybook-react-demo/ you will see how I have created few stories. Lets analyze those

stories folder — having all the stories
stories/buttons.stories.js — Shows all different patterns of button components in reactstrap
stories/table.stories.js — Shows different patterns of table components in reactstrap
stories/layout.stories.js — Shows different layout patterns we can design using reactstarp

Story showing different buttons of reactstrap

Story showing different tables of reactstrap

Story showing Different ways of using grid of reactstrap

Now if you closely see the code I grouped 2 of the story under one story group i.e. UI components for buttons and tables and Layout for different layouts.
So all you need to do is to create a function which will return a react component and that component contains your actual standard or re-usable components

But Storybook is not limited to here only, there are lot of addons to enhance the user experience like adding the notes for each of the story for detail explanation, or showing the behavior of components in different viewports.

Lets use one of the addon notes.
1)Install notes addon

npm i -S @storybook/addon-notes

2) Create a file .storybook/addons.js with below content to have it attached with storybook dashboard

import ‘@storybook/addon-notes/register’;

Note — After version 5.3.x no need of addons.js separate file instead write it as below in main.js

module.exports = {
   stories: [‘../src/stories/*.stories.js’],
   addons: [
      @storybook/addon-notes/register
   ]  
};

3)Now there are different ways to provide notes like simple text, or using markdown file etc. Lets see the usage with markdown file.

If you go through the above Github repository, you will see the folder as src/markdowns(its not mandatory, you can place anywhere you want) where we have markdown files for each of the story.
Below simple steps to add a markdown file as a notes -

1)Create the markdown file 
2)Attach it to the story in the 3rd parameter of add method like below
 .add(“story name”,Function to return react,{
 notes: markdown file
 } )

Similarly, you can check for viewport addon in the Github repository. How the iPad and iPhone story shows the layout of the same component on different screen sizes.

iPad viewport addon

iPhone viewport addon

By below code snippet we can add those viewports

import {storiesOf} from "@storybook/react";
import markdownNotes from "../markdowns/layout.markdown.md";
storiesOf(“Layout”,module)
.add(“Grids”,storyFunction,{
   notes:{markdown:markdownNotes}
})
.addParameters({ viewport: { defaultViewport: ‘ipad’ }})
.add(“iPad Layout”,()=><ResponsiveLayout />)
.addParameters({ viewport: { defaultViewport: ‘iphone5’ }})
.add(“iPhone 5 Layout”,()=><ResponsiveLayout />)

So above snippet will create 3 stories

Grids — with the default screen size set by storybook itself, which can also be changed from the config.js

iPad Layout — with the screen size of an iPad

iPhone 5 Layout — with the screen size of an iPhone 5

For more configuration related stuff you can refer https://medium.com/storybookjs/declarative-storybook-configuration-49912f77b78

Happy UI Documenting :)