Dependency discovery in Storybook
Dependency tracking and analysis made for component libraries
Storybook is the most popular UI component explorer. It powers frontend infrastructure for Shopify, IBM, Salesforce, and Airbnb, and 30,000+ public GitHub projects.
In the beginning, Storybook was used to help developers build components in isolation. Developers created component libraries containing hundreds of components and thousands of stories. But large Storybooks can be tough for teams to manage. Components get lost or forgotten at that scale.
I’m thrilled to announce addon-deps, a new Storybook addon that helps developers visualize the dependency graph for components which makes browsing your component library faster and more intuitive. The addon gives you x-ray powers to see which components are reused, where, and how often.
- 👷♀️ Developers get insight into component relationships and composition.
- 👨🎨 Designers see the impact of component’s changes on the whole library.
- 🕵️♀️ Testers pinpoint areas that need testing when a component updates.
Why should you care about dependency?
Modern UIs are composed of hundreds of reusable components that are reused and reconfigured to serve wildly different purposes. For instance, a humble button might appear on marketing pages, docs, or inside the app itself.
Reusable components are dependencies that help you remove repetitive code that’s already been written by you or someone else. But keeping track of where/how these dependencies are used can be pretty tricky when you have hundreds of components and thousands of stories. You might wonder:
- “Where else is this component used?”
- “What components are used on this screen?”
With the deps addon, teams can easily track component dependencies in component libraries (and design systems). This unlocks the ability to predict the global impact of any component change. You can also discover which components are used on a given screen.
Install and configure storybook-deps-addon
1Install the plugin:
npm i -D storybook-addon-deps2 Add the preset in your `.storybook/main.js`file.
module.exports = {
addons: ['storybook-addon-deps', ...]
...
}3Configure the DocsPage and configure any parameters .storybook/preview.js (former .storybook/config.js):
import { DocsPage } from 'storybook-addon-deps/blocks';
addParameters({
docs: { page: DocsPage },
dependencies: { withStoriesOnly: true, hideEmpty: true }
});withStoriesOnly: if true, will display only dependencies components that have Storybook stories written for them. This removes some of the system clutter in the dependencies (ie the React library dependencies). However this only works when you have built a hierarchical UI library with components that are composed from other components in the library. Default: false.
hideEmpty: if true, will completely hide a dependency/dependents block when the current component has no dependencies data. Default: false.
4 Show dependencies in Storybook Docs. There are three ways to integrate the addon: DocsPage, MDX stories, and an addon tab. Use one or all depending on your workflow.
DocsPage integration
DocsPage (5.2+) automatically generates best practice UI docs from your components. We’ll further customize the default DocsPage to show the “Dependencies” and “Dependents” DocBlocks via `.storybook/preview.js` as outlined above in pt 3.
Specify the updated DocsPage from the deps addon.
import { DocsPage } from 'storybook-addon-deps/blocks';addParameters({ docs: { page: DocsPage } });
You’ll now see DocBlocks for “Dependencies” and “Dependents”.
MDX integration
MDX (Storybook 5.3+) is a syntax for writing Markdown and stories side-by-side in the same .stories file. In contrast to DocsPage, which provides smart documentation out of the box, MDX gives you full control over your component documentation.
Import the Dependencies and Dependents DocBlocks in your MDX story. Here’s an example using aButton.stories.mdx file.
import { Story, Preview, Props, Description, Meta } from '@storybook/addon-docs/blocks';
import { Button } from '@storybook/design-system/dist/components/Button';
import { DependenciesTable, Dependencies, Dependents } from 'storybook-addon-deps/blocks';<Meta title="Design System|Button" component={Button} parameters={{ component: Button }} /># Selected story
<Preview withToolbar={true}>
<Story id="." />
</Preview># Properties
<Props of={Button} /># Table dependents + dependencies
<DependenciesTable titleDependencies='Dependencies' titleDependents='Dependents' of={Button} /># Dependencies doc block
<Dependencies of={Button} /># Dependents doc block
<Dependents of={Button} />
Your MDX docs will now show that component’s deps.
Addon tab for dependencies tree
In Storybook, you can also add custom addon panels. The storybook-addon-deps plugin offers an exploratory tree in its own tab.
To register the dependencies tree tab in storybook, replace the presetwith preset-explorer in `.storybook/main.js`:
module.exports = {
presets: ['storybook-addon-deps/preset-explorer', ...]
...
}This will yield a new “Deps” tab that gives you an interactive dependency browser.
Audit your project’s dependencies
In addition to the detailed usage and dependencies information for each component, storybook-addon-deps also provides several charting blocks for overall project analysis.
You can include these blocks in any MDX storybook story. For example, you can make a docs-only MDX story to display these charts on the intro page to your Storybook.
import { Meta } from '@storybook/addon-docs/blocks';import { ChartComponentUsage, ChartStoriesPerComponent } from 'storybook-addon-deps/blocks';<Meta title="About|Dashboard" /><ChartStoriesPerComponent /><ChartComponentUsage />
Stories per component
Displays how many stories are written for each component. More stories means more coverage for the component.
import { Heading } from '@storybook/addon-docs/blocks';
import { ChartStoriesPerComponent } from 'storybook-addon-deps/blocks';<Heading>Stories per component</Heading>
<ChartStoriesPerComponent
height='500px'
options={{
sliceVisibilityThreshold: 0.04,
pieSliceText: 'value',
s3D: true,
pieHole: 0.7,
}}
/>
Configuration it to swap out the pie chart for a bar chart.
<ChartStoriesPerComponent
height='500px'
chartType="BarChart"
options={{
legend: 'none'
}}
/>Components by usage
Displays how many times each component is used by other components.
import { Heading } from '@storybook/addon-docs/blocks';
import { ChartStoriesPerComponent } from 'storybook-addon-deps/blocks';<Heading>Components usage</Heading>
<ChartComponentUsage
height='500px'
options={{
minColor: '#009688',
midColor: '#f7f7f7',
maxColor: '#ee8100',
}}
/>
The charts used are Google Charts and all their properties are applicable. Detailed information on configuration options is available from Google documentation, for example Pie Chart options.
Other frameworks
Checkout the GitHub repo for examples in other frameworks beside React:
Get involved
Addons are a flourishing part of the Storybook ecosystem. They give devs the ability to customize the Storybook workflow to their needs and share those customizations with others.
Browse addons
Learn how to build addons
Storybook is maintained by 900+ open source contributors and guided by a steering committee of top maintainers. If you are interested in contributing, check out Storybook on GitHub, create an issue, or submit a pull request. Join us also in the Discord chat. Donate on Open Collective.
