Build Bulletproof React Apps with Storybook and Chromatic
Two years ago Wave had a problem: we needed to make changes to a user onboarding flow. Working on this flow required us to create a new account for every single run. We needed a way to work on only one React component in this flow, with the rest of the app mocked out.
Enter Storybook, a tool for developing frontend components in isolation. You create ‘stories’, or mocked states, by manually defining props for a component, then Storybook renders each one in its standalone app. This results in components that are fully decoupled from their surroundings.
Not only did Storybook solve our initial problem, but it sped up delivery by enabling teams to do frontend work before the backends were ready. Two years later, we have an app made up of robust, testable components.
Recently, we discovered that people were unwittingly breaking each other’s stories. To address this, we added Chromatic to our workflow. Chromatic is a tool that compares snapshots of your stories to highlight visual changes. It uses git to make comparisons between your base branch (usually master) and your feature branch, allowing any member of your team to easily verify that all new and changed components are visually correct. As a bonus, the whole flow is tightly integrated into the GitHub required checks panel.
While we started using Chromatic because people were breaking each other’s stories without realizing it, we were also excited about the prospect of automated visual regression testing — and the results far exceeded our expectations. Our enhanced automated test suite has empowered our design systems team to move faster with more confidence. As a bonus, designers are now getting more involved in pull requests by verifying all visual differences that are caught by Chromatic.
Because of the importance that we put on having Chromatic as a step in our CI, Wave has decided to share our setup with the community. To help make it is simple as possible, we published an Orb. Orbs are a new feature in CircleCI v2.1 that allow the community to package and publish CircleCI executors, commands, and jobs. CircleCI hosts the docs for the orb as well as the source here. Keep reading for instruction on setting up Chromatic as well as an example config.
3 Easy Steps to Set Up Chromatic in CircleCI
Note that this tutorial assumes you have a frontend app that is on GitHub and running Storybook.
- Sign up for Chromatic and CircleCI (if you haven’t already)
- Install Chromatic in your project: `yarn add -D chromatic`
- Create a `.circleci/config.yml` file if you don’t have one and put the following in it:
CircleCI Workflows
The first workflow holds until you tell it to run. You do this from the GitHub UI, telling CircleCI you are ready to run Chromatic. This process ensures that when your code is ready — and only when it’s ready — it gets run through Chromatic. We have found that this keeps us from wasting our snapshot quota. This “don’t run until I tell you to” workflow is also a great place to put other jobs that may eat up a quota.
The second workflow is where you will put the rest of your tests and linters. This runs on every commit, including when you merge to master.
Note the filters on our jobs. These are there to optimize our Chromatic flow based on git branches. The first filter ensures that we don’t run the `ready` workflow (which waits for approval) on master. This filter is important because without it, our checks on master would always be yellow. The second filter ensures that our `run-and-accept-all` job only runs on master. This filter is critical because without it Chromatic would never report changes.
If you are not familiar with CircleCI workflows, read about them here.
Protected Branches in GitHub
To get the most out of Chromatic and other CI tools, you should enable GitHub’s branch protection feature. Doing so ensures that pull requests need to pass checks and get code reviewed before being merged into master.
Note that in the example config file we are only running Chromatic. In a real app, you would likely be running one or more linters, a formatter, a test suite, and maybe a typechecker. Once the changes caught by Chromatic are manually approved, the GitHub check will pass.
The Payoff
Using this workflow, we have been able to make big changes across our React and SCSS code with confidence. The more things we have in Storybook, the more coverage we get in Chromatic. Wave now builds all new components in Storybook. We have seen huge gains in output from adopting this flow, and we hope that you do as well.
