Main image

5 weeks of Storybook: 5 lessons learned

Published: 3/1/2021

In our last article, we talked about how we’re rebuilding Circuit For Teams web app.

If you read it (you really should!), you already know that we’re rebuilding it using a component-driven development pattern and a handful of battle-tested front-end tools like Storybook, Tailwind, etc.

Today we’re diving deep into one of those tools and sharing what we learned on the road to front-end excellence.

Let’s talk Storybook!

Give the docs a full read from time to time

Okay, I know that that sounds like generic advice that applies to every tool that you’d use. And that’s true. I’ll give you that.

I’m sharing it today because sometimes we forget that the open-source tools we so much depend on update constantly, and their docs generally follow suit.

See, a month ago, when we started working on our component library, I was relatively confident in my Storybook skills. It turns out the last version of Storybook I worked with was v5.3, and a lot changed in the current v6.1.

Fortunately, that only cost me an afternoon catching up with the docs and updating our v5.3 addon implementation to the new and improved @storybook/addon-essentials.

Long live @storybook/addon-essentials

Speaking of addons, this is the addon if you’re looking for a way to make your Storybook even more convenient.

“Essential addons” is a kit of official addons by Storybook’s maintainers. It extends your component playground with, well, some pretty essential stuff like documentation, debugging and UI control tools.

Here’s a gif of the Control addon that comes bundled with essentials. It allows you to update component props from a very handy form interface.

Super cool! 

CSF and external exports

Storybook uses the Component Story Format which means, among other things, that it interprets every named export in your stories file as a story.

For instance, export const someRandomData = [1,2,3] is processed as a story the same way that export const text = () => <Button>Hello</Button>;.

That creates a curious scenario where it is impossible to export simple data from story files.

Imagine that you have three different Select components that share the same initial data; not being able to import that data form a story file can be frustrating.

Thankfully, there’s a solution! CSF allows you some fine-grained control over which named exports Storybook handles as stories. Here’s an example of includeStories and excludeStories args straight from Storybook docs:

Fresh previews on every PR

I don’t know about you, but I love when I don’t need to locally build a branch when reviewing a pull-request.

Having GitHub + Netlify (or your web app platform of choice) build a new Storybook with a colleague’s latest changes is a godsend when reviewing a pull-request.

Review the code as you would and check the preview URL for visual feedback and that extra validation level. Just keep an eye on that build minutes quota.

There is no standard way to organise components

I mean, that are wrong ways to do that but what I’m saying here is that Storybook does not enforce a standard on how you should separate/categorise or stories. It gives you a flexible API to work with but leave the decision to you.

One thing that it does, however, is sharing examples of other teams design systems, so you can check them out and reflect on what works and what doesn’t. IBM Carbon’s Storybook lists all of its components in the same hierarchical level, while GitLab’s separates its components into Base, Charts, Regions, Utilities, Directives and SCSS.

You can see that this is more about organisation than code, and, as with a lot of flexible APIs, there is a significant potential for bike-shedding. So go with what feels right, and remember that you can always reorganise your components relatively quickly.

What’s next

To be honest, we learned way more than five lessons in the past month, but this article was getting a bit on the bigger side. 😅

In the upcoming weeks, you can expect our take on Storybook + Typescript, how we’re handling icons, our take on what we don’t like about it and other API quirks.

Feel free to ping us at @CircuitApp on Twitter if you have any question or feedback about this post. It’s always a pleasure sharing what we know.

Until next time 👋