Chromatic and storybook



The process of creating small components library supported by chromatic and storybook.

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
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.
is not reserved only for React. Check the
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
. 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
The script can ask you about migration to
if you are using
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
Changes from this step can be found in this
5. Adding first story
Let's add story for
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
6. Chromatic
When you have
- you can use
. Now the magic starts.
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.
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
and log in via your source control provider.
Now create
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
file - just confirm that.
Changes from this step can be found in this
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
9. Last improvements
In this step we remove
from repo. Just add that file name to
Also, you need to remove the project token from the source repository and use it from
files as documentation recommends. Also, we can achieve that by
. I prefer this approach.
After that remove
"chromatic": "npx chromatic --project-token=YOUR_TOKEN"
- it's not needed. Soon you will run your builds automatically.
Changes from this step can be found in this
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
. Now to test that follow the steps below:
Changes from this step can be found in this
to play with.
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!