Product Analytics for Storybook: Introducing the Amplitude Storybook Add-on

Have you ever wondered how people use your Storybook? Or if anyone visits it in the first place?

On the Front-end Infrastructure/Design Systems (FIDS) at Amplitude we felt that our Storybook could be improved. Instead of making random changes, we decided to use Amplitude to capture product analytics about our documentation site.

That’s why we built the Amplitude Storybook add-on. It helps design systems teams capture Storybook usage metrics in Amplitude.

Now, we understand current usage patterns and whether our changes improve or degrade the quality of our documentation. We can also trace adoption trends over time and understand which components are most heavily used.

Why did we build this?

On the FIDS team, we use the Amplitude Storybook add-on to answer questions pertaining to adoption, prioritization, and interface usability.

For example, we capture analytics about the following questions:

1. How many people use our documentation site right now? (proxy for adoption)
2. What pages have the most traffic and what pages have the least traffic? (proxy for prioritization)
3. How do people interact with the args functionality in our stories? (proxy for interface usability)

Example Charts

Weekly Unique Users Viewing Storybook Documentation

We capture information about the number of users who view our documentation in the following chart:

This chart tracks the number of times the “viewed documentation” event occurs every week. It’s a good sign if that number increases week over week.

This is a useful metric to capture because it helps us to understand adoption trends over time.

Most Commonly Referenced Storybook Categories

In our Storybook, we keep different types of stories (layout components, bases, variants, etc.) separate in different sections. It’s important for us to know which sections of our documentation are most trafficked and how our teammates are using them.

The chart below keeps track of the number of unique times documentation was viewed, and then groups it by category:

We are currently working on migrating from an older component library to a new one, so tracking these metrics helps us to understand how many consumers are looking at legacy components vs. new ones.

We can also see whether anyone is looking at our more philosophical and theoretical documentation, rather than mostly looking at how to use component APIs.

Most Commonly Referenced Stories/Components

It’s also useful for us to know which stories are most frequently viewed. We can track this by grouping all of the “viewed documentation” events by page. At the moment, the most viewed component is our `Inline` layout component:

Keeping track of this data helps us to understand which components are being used regularly and guides us to prioritize updates to certain components over others.

Finally, we also keep track of how many users update a story’s arguments. We were curious about whether readers of our documentation found that feature helpful or not. This chart displays the number of times the “update story args” event occurs week over week:

This data can help us understand whether people regularly tweak and interact with our story arguments.

Getting Started

The first thing you’ll need to do is sign up for Amplitude. If you already have an account, great! If you don’t, you can sign up here for free.

Once you have an account, you can create a new project which will have an associated API key. To do this, navigate to the Settings page.

Then, select Projects in the sidebar.

In the top right hand corner, click the Create Project button and follow the instructions.

Next, install the package as a devDependency in your project:

yarn add @amplitude/storybook-addon-amplitude --dev

Next, add the add-on in storybook/main.js:

module.exports = {
  addons: [
    '@amplitude/storybook-addon-amplitude/preset',
  ]
}

Finally, set your Amplitude API keys in ./storybook/manager.js.

window.AMPLITUDE_DEV_API_KEY = ‘<amplitude-dev-api-key>’;
window.AMPLITUDE_PROD_API_KEY = ‘<amplitude-prod-api-key>’;

Now your storybook will begin emitting events to your project in Amplitude. You’re ready to start creating charts in Amplitude!

Final Thoughts

We’re so excited to share this project with the design systems community, and we hope you’re excited to try it out. We can’t wait to see what new and interesting ways the community uses Amplitude to track Storybook usage.

Want to talk about this post? Discuss on Github →

I want to extend a huge thank you to Jack McCloy (@JackMcCloy), Dan Mall (@danmall), Kaelig Deloumeau-Prigent (@kaelig), and Josh Goldberg (@JoshuaKGoldberg) for providing feedback on this post.