Tales from the Library, Part 3

The Neverending Storybook

This is the third in a series of articles about a component library we recently completed. If you missed the first two articles, you can catch up here and here.

If you’re one of those straight-to-business types, we also have a demo project and source code containing all the tips found in this article.

Storybook

In this installment, we’ll cover a tool that isn’t used in building UI components, but is just as critical to their livelihood. We’re talkin’ about Storybook, a standalone web framework that acts as a staging platform for components in your browser.

When visiting a Storybook instance, users are presented with stories, or live in-browser use cases of each component. Stories are self-contained and don’t require any business logic to run. It’s as if each component lives in its own test chamber. This makes demoing to clients and your team a total breeze.

For example, here’s a story for a component that displays a list of books:

Storybook is compatible with component libraries developed using React, Angular, and vue.js. Ours was built using React, but the tips in this article are generally applicable to all three platforms.

We’ve mentioned this before, but IBM’s Carbon Design System is also a great example of a complete component library with Storybooks for React and vue.js components.

Choosing the Right Addons

Storybook is cool on its own, but it gets really hot when supported by a host of “addons,” which can be found off the main Storybook site.

You can plug any of these (and more) into your Storybook. Most are ready out-of-the-box.

We find the following addons to be indispensable:

Knobs
With knobs, non-programmers can edit a component’s properties right in the page. This makes it super easy for QA to visually check a control for different inputs. Clients (and designers) can also adjust the knobs to preview different states, encouraging feedback and accountability throughout the dev process.

Info (React only)
This displays a component’s usage along with a “Prop Table,” a formatted list of a component’s properties. This table is populated using an additional addon, storybook-addon-react-docgen.

a11y
Checks stories according to accessibility standards, compiling a list of passes and violations based on WCAG “A” and “AA” compliance levels.

Links
Supports links to navigate between different stories. More on this later!

Staging and Selective Publishing

During development we had two instances of Storybook running: a client-facing production site and an internal staging site. However, we only wanted components to appear in production when they were finished — nothing in progress was to be exposed!

An obvious answer would have been to deploy different git branches or tags, but this didn’t work for us, because we tend to revisit components throughout our development. Rolling back would also mean losing any components that were added in the meantime. Consequently, we needed a way to tell Storybook which set of stories to display. Either show stories for all components or only stories for finished components. And because this was being added to our CD pipeline, we needed it to be configurable from the command line.

Our solution was to maintain a whitelist of file-paths to finished components, allowing components to be filtered before being pushed to our client-facing site. We set up this little whitelist in javascript in our .storybook folder:

We’re exporting two filter functions: ‘All,’ that lets everything through, and ‘Finished,’ which only lets through stories whose filepath is included in our whitelist, “finished.json”.

And supplied it with the following JSON:

Then, we connected the whitelist filter to our Storybook instance, in storybook.config.js:

Finally, we added the following scripts to package.json so that we could launch everything from the command line:

What we’ve done here is subtle, but it saved us some serious headaches when deploying our code to the client. Using this approach, we can now effectively “abridge” our Storybook, only allowing components to appear when they’re 100% ready!

Mirco-managing (React Only)

Certain collections of components, such as lists, accept arrays of child props. Consider this super simple BookView, which consumes a title and an author:

Then, BookListView comes along and wants to display a collection of BookViews, so it consumes a list of BookView Props:

This is all fine and dandy until we open up the info panel on the BookListView story and look at the Prop Table that was generated:

Unfortunately, if I were looking at this codebase for the first time, I’d have no idea what type of object is expected in “books.” The good news is, we already have documentation for the BookView props in the BookView story. So if we could link the BookListView props table to the BookView story, developers could click down the hierarchy to see the data-types there.

Luckily, we’re able to just that by making a custom Prop Table component that links to subcomponents’ stories right in the storybook-info panel!

We rolled our own Prop Table by following this guide. Don’t worry, our full source code is at the end of this article ;)

The custom Prop Table scans the component’s Prop Type documentation for “story” and optional “kind” keywords next to each field, which it feeds to storybook-link to tie nested types to their respective stories.

We only have to do a little bit of setup in the props for BookListView:

And voilá! The full thing in action:

We weren’t able to to change how the parent component’s props appear in the table, but we went ahead and threw a shortcut in to the children as a workaround. That’s how we do it ‘round here!

Conclusion

If you’re developing a component library, we can’t recommend Storybook enough. It lets you stop worrying about your demos and start focusing on the components themselves!

As a platform for framing component content, we can also expect Storybook to continue to evolve. We’ve already seen this from the vibrant addon community that’s ballooned around it in just a short time.

Once again, be sure to check out our Storybook demo and grab the source code.

thirteen23 is a digital product studio in Austin, Texas. We are an award-winning team specializing in human-centered design. Ready to build the next big thing? Let’s talk.

Find us on Facebook, Twitter, and Instagram or get in touch at thirteen23.com.