6/23/2018Time to read: 5 min
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.
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 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 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.
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.
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:
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.
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!