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.
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.
This guide shows you how to setup an addon from scratch. Alternatively, you can jumpstart your addon development with the
We recommend a common addon file and directory structure for consistency.
|dist||Transpiled directory for the addon|
|src||Source code for the addon|
|preset.js||Addon entry point|
|package.json||Addon metadata information|
|README.md||General information for the addon|
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
Once you've gone through the prompts, your
package.json should look like:
We'll need to add the necessary dependencies and make some adjustments. Run the following command to install the required dependencies:
Initialize a local Storybook instance to allow you to test your addon.
Next, create a
.babelrc.js file in the root directory with the following:
package.json and add the following script to build the addon:
yarn buildat this stage will output the code into the
distdirectory, 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 modify Storybook's UI.
Now let’s add a panel to Storybook. Inside the
src directory, create a new file called
register.js and add the following:
keywhen you register the addon. It 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
My Addonto the UI
- When selected, the
panelrenders the static
Finally, let’s hook it all up. Change
.storybook/main.js to the following:
preset.jsas the entry points.
yarn storybook and you should see something similar to:
Next, let’s replace the
MyPanel component from above to show the parameter.
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.
When Storybook was initialized, it provided a small set of example stories. Change your
Button.stories.js to the following:
After applying the changes to the story, the Storybook UI will show the following:
Before publishing the addon, we'll need to make one last 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.
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:
package.jsonfile with metadata about the addon
- Peer dependencies of
preset.jsfile at the root level written as an ES5 module
srcdirectory containing the ES6 addon code
distdirectory containing transpiled ES5 code on publish
- GitHub account to host your code
- NPM account to publish the addon
Reference the storybook-addon-outline to see a project that meets these requirements.
Learn how to add to the addon catalog.
In the previous example, we introduced the structure of an addon but barely scratched the surface of what addons can do.
To dive deeper, we recommend Storybook's creating an addon tutorial. It’s an excellent walkthrough covering the same ground as the above introduction but goes further and leads you through the entire process of creating a realistic addon.
To help you jumpstart the addon development, the Storybook maintainers created an
addon-kit, use it to bootstrap your next addon.