Write an addon

One of Storybook's main features is its robust addon ecosystem. Use addons to enhance and extend your development workflow. This page shows you how to create your own addon.

What we're building

For this example we're going to build a bare-bones addon which:

Adds a new panel in Storybook.
Retrieves a custom parameter from the stories.
Displays the parameter data in the panel.

Addon directory structure

We recommend a common addon file and directory structure for consistency.

Files/Directories	Description
dist	Transpiled directory for the addon
src	Source code for the addon
.babelrc.js	Babel configuration
preset.js	Addon entry point
package.json	Addon metadata information
README.md	General information for the addon

Get started

Open a new terminal and create a new directory called my-addon. Inside it run npm init to initialize a new node project. For your project's name choose my-addon and for entry point dist/preset.js.

Once you've gone through the prompts your package.json should look like:

Build system

We'll need to add the necessary dependencies and make some adjustments. Run the following commands:

Initializing Storybook adds the building blocks for our addon. If you're building a standalone Storybook addon, set the React and Storybook packages as peer dependencies. This prevents the addon from breaking Storybook when there are different versions available.

Next, create a .babelrc.js file in the root directory with the following:

Babel configuration is required because our addon uses ES6 and JSX.

Change your package.json and add the following script to build the addon:

Running yarn build at this stage will output the code into the dist directory, transpiled into a ES5 module ready to be installed into any Storybook.

Finally, create a new directory called src and inside a new file called preset.js with the following:

Presets are the way addons hook into Storybook. Among other tasks they allow you to:

For this example, we'll just modify Storybook's UI.

Add a panel

Now let’s add a panel to Storybook. Inside the src directory, create a new file called register.js and add the following:

Make sure to include the key when you register the addon. This will prevent any issues when the addon renders.

Going over the code snippet in more detail. When Storybook starts up:

It registers the addon
Adds a new panel titled My Addon to the UI
When selected, the panel renders the static div content

Register the addon

Finally, let’s hook it all up. Change .storybook/main.js to the following:

When you register a Storybook addon, it will look for either register.js or preset.js as the entry points.

Run yarn storybook and you should see something similar to:

Storybook addon initial state

Display story parameter

Next, let’s replace the MyPanel component from above to show the parameter.

The new version is made smarter by useParameter, which is a React hook that updates the parameter value and re-renders the panel every time the story changes.

The addon API provides hooks like this so all of that communication can happen behind the scenes. That means you can focus on your addon's functionality.

Using the addon with a story

When Storybook was initialized it provided a small set of examples stories. Change your Button.stories.js to the following:

After applying the changes to the story, the Storybook UI will show the following:

Root level preset.js

Before publishing the addon, we'll need to make one final change. In the root directory of the addon create a new file called preset.js and add the following:

This auto-registers the addon without any additional configuration from the user. Storybook looks for either a preset.js or a register.js file located at the root level.

Packaging and publishing

Now that you've seen how to create a bare-bones addon, let's see how to share it with the community. Before we begin, make sure your addon meets the following requirements: