Building a Component Library with Storybook for a React Frontend Dashboard

Frontend developers at adjoe are currently working hard to reimagine our dashboards. This is so that Supply and Demand partners can view statistics, run ad campaigns, and bring new apps live with our Playtime SDK. This means coming up with a new look, new features, and a new codebase with state-of-the-art frameworks.

When working on React components that are based on a custom design kit made by our designers, it’s important to keep an eye on various elements. These include expected behavior as well as design implementation details like colors, borders, and margins. You should also have an overview of the components that have already been implemented in order to construct complex pages. To solve these criteria, we implemented Storybook, a component library framework, into our codebase.

In the following series of short articles, I – as a frontend developer – will show you what the codebase should look like in order to get the most out of the tool. I’ll also lead you through the process of integrating a Storybook component library.

What Is Storybook?

Storybook is a third-party package for frontend projects that adds a component library to a project that can be run locally or deployed to either Storybook’s own hosting service Chromatic or to a custom service. 

Components are added to the library by adding a .stories file next to the component, which imports and renders it with user-controlled props. In addition, prop commenting and MDX can add documentation to the story. Thus, Storybook becomes an interactive list of all your components that also works as component documentation.

How Should My Codebase Look for Storybook to Work?

I first brought up the idea to use Storybook in our codebase during a company hackathon. Back then, I tried to implement it in our dashboards. 

This turned out to be unsuccessful, as our dashboard code was using complex containers. This meant that writing stories for these components was nearly impossible due to how they used global store and API calls within them. 

In order to write efficient stories for your components, you have to make sure that they are as isolated as possible, working only with the props they get from their parent. That also means that you should only write stories for components, not containers. It is possible to use plugins for Storybook to mock API calls and global store. However, in my opinion, this is not the intended use of the tool.

How Do I Integrate Storybook into My Project?

First of all, you have to make sure that you already have an established project. Storybook only works in already existing codebases. This is due to how it looks through your project before setting it up correctly.

Then, installation is as easy as running one command:

npx storybook init

It will look through the codebase in order to implement the correct settings. After it has finished, you can open the storybook with one of the following commands depending on your project’s setup:

yarn storybook

npm storybook

These commands will open the Storybook local page in your browser. It will show you some tutorial pages and default components to get you started.

Storybook will automatically look for .stories.* files in your project. But you can change the search path easily by editing the main.js file created in the .storybook folder. Here, you can also add plugins and change options.

module.exports = {
 "stories": [
   "../**/*.stories.@(js|jsx|ts|tsx|mdx)",
 ],
 "addons": [
   "@storybook/addon-links",
   "@storybook/addon-essentials",
   "@storybook/addon-interactions",
   "storybook-addon-react-router-v6",
 ],
 "framework": "@storybook/react",
 "core": {
   "builder": "@storybook/builder-webpack5"
 }
}

Based on the styling approach you use, you might also find that your stories are not using the style of your project. In our dashboards, we use MUI theme for global style guidelines. In order to make sure all story components are using this theme, we had to add a new file to the .storybook folder: preview.js.

Here, you are able to set decorators, an array of functions that get the story as a parameter, and return the customized JSX element. In our example, we added the MUI license key for paid MUI components in use and wrapped the story in our theme.

export const decorators = [
 (Story) => {
   setMuiLicenseKey();
   const ThemedStory = withTheme(Story);

   return (
     <ThemedStory />
   )
 },
];

At this stage, you can browse through your stories locally. But what if you want to share your storybooks with your colleagues?

There are two options to host your storybook online. You can either use your own hosting service, or you can use Chromatic, a hosting service uniquely made for Storybook. There, you can set up your project, set up access settings, leave design reviews, and use versioning for your uploads.

To create a new project, you first have to create a Chromatic account and initially adjust some settings. Follow the setup instructions and you will get a secret Chromatic token that you can use to upload your storybook to the platform. You can upload it manually via the command:

yarn chromatic —-chromatic-token=YOUR_TOKEN

You can also set up your pipeline to upload it automatically in your CI. This is the recommended way of loading your storybook. Chromatic also expects the upload to be performed on a consistent branch, so make sure you upload it via your develop or master branch. 

In our case, we created a new GitLab job to upload the storybook after our test pipeline on the master branch was successful.

job-upload-storybook:
 image: node:latest
 stage: upload
 environment:
   name: test
 except:
   variables:
     - $TEST_SKIP == "yes"
     - $TB_SKIP == "yes"
 script:
   - docker stop storybook || true
   - docker rm storybook || true
   - docker run --name storybook -td -v $(pwd):/usr/src/project --env CHROMATIC_PROJECT_TOKEN=$CHROMATIC_PROJECT_TOKEN node:latest
   - docker exec storybook sh -c 'cd usr/src/project/beta; yarn bootstrap; yarn chromatic'
   - docker stop storybook
   - docker rm storybook
 only:
   - master

With this we made sure that the new version of Storybook always has an “ancestor” version to compare it to, and thus makes the automatic UI comparison work correctly. More on that feature in a later article.

What’s Next?

After building a component library with Storybook, you should have a constantly up-to-date Storybook to use for documenting and viewing components. It will also automatically check for UI differences between your upload and the last version uploaded, and you can review these changes to accept or deny them.

Stay tuned for my next article, in which you will learn how we wrote stories for both small components like buttons and more complex components like dropdowns or filters. I’ll also talk about utilizing everything the Storybook stories writing toolkit has to offer.