Deploy Storybook on Chromatic for Integrated Development

[00:00 - 00:19] In this course, we learned that without Storybook, in order to build a feature, the developers have to develop AND integrate it at the same time, and sometimes the feature is in a hard to reach place. And at the end, they have to make a pull request, which could be pretty big, and they would have to publish the entire application to test environments so that they could get feedback from their colleagues.

[00:20 - 00:26] But with Storybook, the flow is a little different and much simpler. Your development is focused, and then you integrate into the app.

[00:27 - 00:37] But for now, you can build and document the entire component in isolation in Storybook, and then you make a smaller, concise PR. And then you can publish your Storybook so your colleagues can review the changes.

[00:38 - 00:41] But so far, we have been using Storybook locally. We don't have a way to publish it yet.

[00:42 - 00:54] But in this lesson, we will be setting up a cloud-based service that integrates perfectly with Storybook, and that is called Chromatic. Chromatic is a free service for publishing your Storybook made by Storybook containers.

[00:55 - 01:11] It offers a lot of interesting features, such as you can publish your Storybook , you can run visual regression tests on it, which can be reviewed by your team, and can be automated in PRs. So with Chromatic, you can deploy your Storybook for every single commit, PR, or branch.

[01:12 - 01:26] It can either be publicly available or private under authentication, like email , GitHub, or other providers. And it offers a paid visual regression testing service that takes snapshots, like screenshots, love each Story and compares them with the previous versions.

[01:27 - 01:36] If there are changes, the team gets notified and they can be reviewed. It also has a free plan that offers 5,000 snapshots a month, which is more than enough for you to try out a service and see if it's a good fit.

[01:37 - 01:54] And Chromatic has a process called UI review, which highlights and shows the visual changes all organized in a single page, and that allows non-technical folks like designers and stakeholders to become reviewers and easily identify what changed. And they can give feedback by adding comments, denying, or approving your changes, which will be reflected in your PRs.

[01:55 - 02:05] And all of these things, the deployment, the visual tests, and the UI review will be connected and automated to CI. And this workflow works exceptionally well in collaboration with designers and developers.

[02:06 - 02:13] So let's get to it. To get started with Chromatic, all you have to do is go to chromatic.com and then click on this button, get started now.

[02:14 - 02:26] Once you connect to your GitHub account, you should be redirected to this page. In this page, you can choose a project from GitHub, so click here and then choose your project, whatever name you called it.

[02:27 - 02:33] And then once this is chosen, you're going to get the steps to go further. So we choose a yarn over here.

[02:34 - 02:46] And then all we have to do is to install the chromatic dependency in our project and then run this command with this project token. And this token is quite important because it's going to identify your project within chromatic and make it work.

[02:47 - 02:50] So let's go to our project over here. And if you have Storybook running, just stop it.

[02:51 - 02:59] And then let's install chromatic. And because the project token is quite sensitive, let's just not use it like this.

[03:00 - 03:12] Let's add it to a environment variable so that we can store this safely and chromatic will pick this up automatically. Over here, we're going to set a Chromatic project token.

[03:13 - 03:26] And then you set the value that you just got there. And instead of running this one off, what we can do is we can go into our package JSON and then under the scripts, we can add a new section called chromatic.

[03:27 - 03:37] And over here, we can type the command traumatic. And also because we're going to be setting this up in the future in CI, we don 't want the CI to fail in case there are changes.

[03:38 - 03:48] Just bear with me and do dash dash exit zero on changes. So we just installed the library, we set up the token in the M file and added the script to package JSON.

[03:49 - 03:57] Let's save all of that work in a git commit. So let's just add everything and then put a new commit called add chromatic.

[03:58 - 04:13] So once we have a commit for this, all we have to do is run yarn chromatic. And what this command is going to do is authenticate with chromatic using the token that we set in the M file and then chromatic will build and publish your storybook on the cloud, which is awesome.

[04:14 - 04:28] And after that is done, it will take snapshots of each story in that published storybook and will run visual regression tests against them. However, because there's nothing to compare to for the very first time we run this command, chromatic would just set those snapshots as baselines.

[04:29 - 04:34] And then any changes in the future will be compared to them. And this command might take a hot minute, so you might just want to grab a coffee for now.

[04:35 - 04:44] Cool. So what happened here is that our storybook was published and we actually have a URL for it right here.

[04:45 - 04:50] And there is a setup that we should continue. We have seven components with 23 stories and 23 snapshots.

[04:51 - 05:03] So if we go back to Chrome, we should see this nice page explaining that we publish our storybooks and showing the snapshots taking for the stories. Let's understand what's going on by clicking on the go to your project link at the bottom and will be taken to the builds page.

[05:04 - 05:11] This means this banners. And like I mentioned, every time you run chromatic, it will generate a build of your storybook and you will be able to see all of them in this page.

[05:12 - 05:25] So if we click on the build, we will see the UI tests which passed as they were auto accepted as baselines. And if we click on view changes, we can see the snapshots taken for each and every one of our stories.

[05:26 - 05:37] And chromatic not only does visual snapshots, but also dom snapshots, which is pretty handy because they also get compared. So if we go back to the build and then we scroll down a little bit, we're going to see this button called view storybook.

[05:38 - 05:43] And that would take you to your very first deployed storybook. It has a unique URL that you can already share with your friends and colleagues .

[05:44 - 05:51] And this is a unique storybook and you can make as many builds as you want. And then you can click on this link at the bottom to go back to chromatic.

[05:52 - 06:00] And just like Git commits refer to code in a point in time, chromatic builds work similarly. The builds will never cease to exist and they are related to a specific Git commit and branch.

[06:01 - 06:13] That means you can always refer back to the implementation of a component and check how it looked and behaved in multiple versions of your code, which is also a great way, by the way, to track the evolution of your project. So we just ran chromatic locally to get our first build and that's pretty cool.

[06:14 - 06:27] But in a real life scenario, you might be working with a team and you would want them to head on automated process with continuous integration or CI so that you can start collaborating with them. And we can automate PRs so that builders don't automatically end colleagues can access our storybook to review the changes.

[06:28 - 06:36] And for that, we need to install chromatic to our GitHub project. So just click on this button and then you're going to have to put your password and then connect to your accounts.

[06:37 - 06:52] And over here you select the repository of which you want to install the app to and then you just approve and install it. So let's dismiss this message and now chromatic has access to PRs and is able to add status checks to them showing whether the changes have been reviewed and approved.

[06:53 - 07:03] But we still need to make chromatic run builds when pushing to GitHub. So to finish our setup, let's just click on this link at the top, which will be redirecting us to the documentation of how to configure this in CI.

[07:04 - 07:10] In fact, we already did the first step before and then we want to configure this to GitHub. So let's just click on GitHub actions.

[07:11 - 07:21] And over here, we have a recipe of a GitHub action that automates chromatic. And just to break things down, we have a workflow called chromatic, which is happening on PUSH and then it will install the dependencies.

[07:22 - 07:33] And after that, it will execute the chromatic action and it's going to be using a project token coming from GitHub secrets called chromatic project token. So let's just go ahead and copy this thing.

[07:34 - 07:42] And this is supposed to be the path. So we go back to our project and we go under GitHub, new folder, workflows.

[07:43 - 07:48] And then the file is called chromatic YML. So we basically just paste this here.

[07:49 - 08:05] And because this automation is going to deploy our storybook in a different environment, we need to provide the necessary tokens for it to work fully. And we have the chromatic project token that we set in the nth file, but there might be other variables that are important, like the Figma one, for instance, which is necessary for the designs add on to work properly.

[08:06 - 08:13] So that means that we need to go back to the workflow file and add the necessary environment variables. And you can do so by adding a new field called mth.

[08:14 - 08:25] And then we set storybook Figma access token, which is also going to be coming from the GitHub secrets. So let's just copy this one and replace chromatic project token with the story book Figma access token.

[08:26 - 08:34] So we're pretty much done with the workflow file, but we still need to set those tokens as secrets in GitHub. So let's go ahead and push the changes that we just made.

[08:35 - 08:42] We just add everything and we commit it with, let's say, add chromatic to CI. Now let's push this.

[08:43 - 08:51] So we just do git push and you should go to your GitHub URL. So let's just click over here, which will open our GitHub.

[08:52 - 08:58] And then we see that our committee is running. And now for the final piece, we just need to create the secrets for both chrom atic and Figma.

[08:59 - 09:12] We can go into settings and then over here at the bottom, we see secrets and then actions. And the reason behind setting these secrets is that you wouldn't want access tokens to be publicly accessible, like directly in the code, because people with bad intentions might actually abuse them.

[09:13 - 09:23] So we create a new repository secret, which is essentially, let's go to our imp file. So we just copy this, we set it, we just copy this and we set it.

[09:24 - 09:30] So we just add this secret. And then we create a new repository secret for the chromatic project token.

[09:31 - 09:35] So we will click here and then we select this one and also save it there. And all right.

[09:36 - 09:46] Now we successfully set up chromatic in our code base. We're now able to make BRs, which will not only publish a new storybook, but will also do visual regression testing in our stories, which we'll be talking about in the next lesson.