⭐ Chromatic and storybook

Intro

The process in which we'll describe the creation of a small, reusable components library that is supported by Chromatic and Storybook technologies.

Prelude

I don't know about you, but I like creating components - especially the more advanced ones.

If you write a component library yourself, and you have a small number of components - testing is not problematic, and documentation is not needed.

However, if you have much more components and they will be used by other developers - you have a problem.

That's why such technologies as chromatic and storybook were created, which you will learn now.

1. Creating example project

Demonstrating these technologies makes no sense without a project. Here I will use a typical React project generated from this repository template.

2. Storybook

Technology that gives you a separate development environment, playground for components, automatic documentation and cool tools for debugging. In simple words - just take all of your components and render them in another app separately.

Storybook is not reserved only for React. Check the docs for more information.

3. Adding storybook to project

It's very simple. Be sure that you are in the root directory of the project. Then all you need to do is type commands described in docs. Just run npx storybook init and wait until process end.

When files are generated - run npm run storybook. This command will run storybook environment and you can start the real fun.

Changes from this step can be found in this commit.

The script can ask you about migration to npm7 if you are using npm8 or higher - just confirm that.

4. Removing generated stories

In our case, we need to document real components which we are using in our small app. So let's remove src/stories directory.

Changes from this step can be found in this commit.

5. Adding first story

Let's add story for InputField component. As you can see, it's a pretty small amount of code to get nice documentation and be able to play with it while developing without any need to run the full app.

Changes from this step can be found in this commit.

6. Chromatic

When you have storybook - you can use chromatic. Now the magic starts. Chromatic it's a game changer. This technology takes your components with stories and builds them into an automatically deployed web app.

You can trigger the build manually or perform it on the pipeline after merging or creating a pull request to a dedicated branch.

The best feature is an option to compare how your components look between different code versions. Chromatic detects that and draws differences for you in UI. The code change is displayed as well.

The code that impacts the look of the components is marked with yellow bullets. After that, you need to go and accept or reject this change. This is a great job for project owner.

7. Chromatic configuration

Just go to chromatic and log in via your source control provider.

Now create chromatic project via choosing repository. A token will be generated. Type npm install --save-dev chromatic in terminal. After this push your commit via git push and type npx chromatic --project-token=YOUR_TOKEN - this create the first build.

The script will ask you to add the build script into package.json file - just confirm that.

Changes from this step can be found in this commit.

8. Detecting first changes

Now you need to change the implementation of the component that indicates changes in UI. After that just type npm run chromatic to trigger a new snapshot build and check changes.

If changes are found you need to review them and accept them. Without this, it will always compare with the previously accepted version of the build :).

Changes from this step can be found in this commit.

9. Last improvements

In this step we remove build-storybook.log from repo. Just add that file name to .gitignore.

Also, you need to remove the project token from the source repository and use it from .env files as documentation recommends. Also, we can achieve that by secrets. I prefer this approach.

After that remove "chromatic": "npx chromatic --project-token=YOUR_TOKEN" from package.json - it's not needed. Soon you will run your builds automatically.

Changes from this step can be found in this commit.

10. Integrating with pipeline

Let's trigger our builds on PR to the main branch. So current workflow will be:

Of course, the process can be aligned with your project. This is just the simplest one.

To achieve that, we need to add pipeline configuration to the repository.

It should be added under .github/workflows. Now to test that follow the steps below:

Changes from this step can be found in this commit.

Full example

Repository to play with.

Summary

After this short adventure, you know how to boost your work with these nice tools.

Feel free to contact me if you have any questions/proposals. Have a nice day and good health!