Chromatic and storybook

10m

Intro

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
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
.
Repository
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!