Oops, I Storybooked your Application!
Hear from Senior Software Engineer II, Nate Kidwell, about Storybook’s life as an application program.
Storybook is a fantastic resource for designers. Just last month, Teachable engineer Mike Kitzman posted about how it helps develop our design system at Teachable. Storybook also is a tremendous tool for collaboration and knowledge sharing. At Teachable, it allows us to view stylistic changes on every pull request, as engineer Kristin Moser also discussed.
Storybook can show all the main UI components used throughout an organization. Not just buttons, tabs, and other widgets, but even the fonts, colors, and other styling elements. However, Storybook is much more than this. In this post, we will discuss its life as an application platform. And even argue that “storybooked components” wind up aligned with best practices.
The Tarpit of “Software in the Large”
One of the problems when developing software is that “feature creep” leads to large projects. Large projects cause complicated code. And complicated code is a nightmare to test, debug, and secure.
And this is a self-reinforcing loop — complicated code inevitably leads to even more complicated code.
In addition, manually testing these larger applications often requires folks to complete several linked tasks. Steps for QA specialists will contain a sequence like:
- Click the “change avatar” button
- Upload a new avatar
- Then visit the user details page
- And you should see the avatar
Forcing folks to manually set up an application’s state like this, over and over again, is a laborious waste of their time.
Storybook to the Rescue
Instead of giving those instructions, an application tester can be linked to a Storybook scenario state (say the profile page of a user with a changed avatar). Therefore, time is saved, complexity is reduced, and all team members can more easily join in the cycle of visual QA.
By demonstrating this behavior in a reproducible story, Storybooks can be subject to automated tests. This testing even includes the ability to “fail” a test that contains a changed screenshot. Services like Chromatic and Percy do a great job of showing “visual diffs” that must be approved on every pull request.
With Storybook, it is possible to view pages and components with the necessary state preconfigured. This state can even align with conventional Redux.
And since stories render in isolation, they are mainly configured via
- Hardcoded variants (sometimes using those state changes)
- Controls
- Interaction testing
This ensures they are “programmatically reachable”. If a rendered component is tricky for a user to produce, then it likewise would be painful to illustrate in Storybook.
All of this provides a forcing function to keep your components clean.
Application Development with Storybook (at Teachable)
At Teachable, we utilize Redux throughout our codebase to manage react state. Despite some gotchas, we find Redux to be useful for keeping a codebase organized. However, setting up a specific Redux state for visual inspection is seldom simple — much clicking and navigation is often needed. But with Storybook, you can put together a state that lets you mock out any details you’re interested in.
Storybook, being a highly extensible platform, has a wealth of addons that tie your stories to additional platforms. Some of these even connect your stories to a Redux store, and we investigated using them with our codebase.
However, we found that a customized approach would fit well with our needs, so we wrote a WithStoreDisplay wrapper component. This component applies actions in sequence (“reducing” over the store) and lets us view a Redux state that could be legitimately reached through “normal Redux.”
So the code:
loads a store up with the actions listed in starterActions already applied (LOAD_TEST_CONFIG etc.) and renders a component (OrderSummary in this case) in the context of that state. The availableActions parameter describes actions that can be fired from an actions panel that then appears when the story is viewed.
Naturally, the storybook also includes a view letting us inspect the Redux store (similar to Redux devtools).
We also use Storybook to target live versions of our application, so certain stories use live API endpoints. This lets us test behaviors in real life, so we can interact with a checkout page that integrates with our actual authentication flow.
Finally, we mock API endpoints in our Storybook stories, so our visual components may be forced to deal with specific API responses (“email taken,” “address updated,” “tax applied”).
Rich Storybook Environments
We are not alone in our belief that Storybook can be used for richer environments. There seems to be a gradual move in that direction.
Some very cool examples include:
SYNTHAX — A game development environment in Storybook,even including a playable shooter!
As the author notes, “It’s very easy and convenient to work on any part of the game in isolation — Meshes, Particles, Animations, UI, Interactive elements, you name it.”
Sourcegraph — The popular code navigation tool has an elaborate storybook that lets you see larger examples of a page with details about the individual story:
Similarly, full web pages are in the storybook for the JSTOR digital library.
In fact, Brad Frost, the creator of Atomic Design, stresses the value of using Storybook for entire pages, and having sections for templates and pages in your storybook, right alongside the rest of your smaller design elements. These composite pages help validate the components that they embed.
In addition to the testing and state benefits that we mention he adds:
Building product templates and pages in Storybook…Connects the dots between the design system and the products it serves…Reduces the UI feedback loop…Demonstrates the view layer of an application as an “interactive comp”…Unlocks new levels of prototyping
The Storybook Project’s Own Feelings on This
The team in charge of Storybook has recently had some posts encouraging its use in a full-stack context. They have written about interaction testing, using Storybook with frameworks, and full-stack Storybook.
Interaction Testing
The Storybook team recently added the ability to relate stories to automated testing (via Playwright working under the hood). This Interaction Testing both demonstrates the interactive behavior of a complication component (e.g. a registration form), and reuses this interaction in automated E2E tests.
In order to take advantage of this, you’d just add test steps inside of a story’s play attribute.
This testing can be stepped through in an interactions panel (as pictured) but also run in CI (or even at the command-line) with a test-storybook command. Note that when an interactive play function is not added, test-storybook still executes a smoke-test to confirm that the story renders successfully.
This all provides an easily integrated gateway to more robust E2E testing.
Framework
The Storybook folks are leaning into its use as an application platform and the next version of Storybook will integrate with many frameworks, even Next.js (which is typically difficult due to the amount of server-side rendering ). For the Next.js case, they are supporting Next’s images, routing, linking, and soon even data fetching.
If you want to tie Storybook to your own framework, there is documentation on building additional integrations (if yours isn’t already supported).
Summary
Storybook is not just for UI design, but it can help you reason through the tougher corners of your application. It even provides you with robust testing to examine your application’s behavior. We get a lot out of taking it into different directions, and hopefully you will too!
