Why we should use Storybook for UI development

Recently I worked on the new login for our company's app. The old login was on jsp. We had a lot of new requirements for the new login, so we rebuilt it from scratch using React.

The new login is a single page React app (SPA) that contains multiple pages, including the login page, forgot password page, security question page, etc. We used React Router for routing, Redux for state management, Redux Thunk for making requests and handling business logic.

Our team also maintains a React component library which provides UI building blocks like buttons, dropdowns, inputs. This helps a lot during the development of login. However, it's still challenging to build a React application. There are some unique challenges with using React in application level vs in component level.

Introducing Storybook

Over the course of developing login, I found Storybook. It's a handy tool to develop and preview part of the application in isolation. It greatly simplified and sped up the development process. Our team also shows a lot of interest in this tool, and we are adopting it for larger projects besides the login.

Storybook, as you can see in the screenshot below, it's a web app that contains a navigation sidebar on the left and detail view on the right. While building our application, we can write "stories", that demonstrate parts of the app, and those stories will be automatically picked up by Storybook. The result is a visual documentation of different aspects of our system. When we click on the title of a story on the sidebar, the detail view changes to display that particular story.

(screenshot from Storybook website)

What are stories

What could be a story? Anything visual.

A story could be a button. Maybe we have a fancy button on the corner of our application page. We could have a story dedicated to the button so that we could see the button on its own.

A story could be a component on its edge case, for example, an input field, where the placeholder is longer than the width of the input. Will the placeholder overflow the input container? Well, we will find out by looking at the story.

A story could be a complete page. Maybe a shopping cart page. We will provide mock data for the items in the cart, so we don't need to log in as a user, select some goods, and click check out. Want to know how our shopping cart look like? Click on that story on our Storybook.

You might be able to see the common theme for stories in a Storybook. They are visual, they are isolated, they don't depend on the backend.

The problem with traditional UI development

As a UI developer, in order to see what visual change my code will produce, the most common approach would be, deploying my HTML, CSS, and JavaScript to the server, and go to our site. In fact, this is what we have been doing. This has very long feedback cycle. Compiling front-end assets takes time (transpiling JavaScript to lower version, bundling, linting ...). Deploying takes time, even though we are deploying to local development server in our own machine, it still takes a while. After deployment, navigating to where the code takes effect also takes time, and require domain knowledge for how to use the application (I have been in my company for a year, I still don't know the most functionality of our application).

The traditional approach of developing UI inside application requires a lot of setups and it's very inefficient. As UI developers, we want to see how things look like when we developing. We can't just change the code and expect it will look fine. Do we really need to deploy again if I just want to change a button from red to blue?

There are better processes for developing UI, for example, running the UI outside of the server, and create a proxy that connects any network request to the server. This way, at least we don't need to deploy every time we change the UI code, but it still requires the server to be running, and it still requires domain knowledge for how the application work.

Storybook for the rescue

With Storybook, the process has changed. Say one day, QA file a bug:

"hey Yiou, that user profile page doesn't display the profile image when the username is too long." -- QA

Ok, after investigating the code for a bit, I found that the main portion of the user profile page is a React component. I will create a story:

After I save the file, Storybook picks up my new stories and automatically reloads. Now I am presented with two previews of user profile page, one with normal length username, one with a very long username.

Looking at the preview, I know what might have caused the bug.

"The long username pushes the user profile image outside of the container. I should consult our UX on what to do here."

I bring my story to the UX.

"Hmm, how will it look when we put the username on a different line" -- UX

I quickly make the change to userProfile.js and Storybook reloads to reflect the change immediately.

"Ah, both the long name and short name look good. let's do that" -- UX

I come back to my desk and deploy my code to the server, do a simple verification and commit my code.

I also commit my story, so that the next person working on user profile page would know how it looks like when the username is too long.

Benefits of using Storybook

Above is a simple story (Eh, a story of ... writing story ... inside storybook?) of using Storybook for UI development. This is a very common scenario in my day to day work. If you are still not convinced how much help it can bring to UI development, I have concluded 3 main points why Storybook is useful:

1. Greatly shorten the feedback cycle for making UI tweaks
2. No dependency on a server, won't accidentally blow up your database
3. A great living documentation for future developers

Of course, there are a lot more benefits, for example, it exposes global dependencies your individual component has, and you know you should keep them as minimum as possible.

Storybook is not just a great tool for development, it can be useful for testing. For more information, you can check out their documentation.

What Storybook is not

Storybook is not a complete replacement of the traditional workflow. At the end of the day, after we make all the UI changes, we still need to deploy our changes to the application and verify that our individual component integrates well with the whole application.

Storybook is not a place to rewrite your application. It really doesn't make sense to reimplement your application in a Storybook. If we see ourselves copying a lot of code from application just to make it show up in the Storybook, we should try to create the wrapper for those application codes and just use the wrapper in the Storybook.

---

That's all I want to say for Storybook. It has helped our team a lot. Check it out if you are interested!