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:
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 |
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:
We'll need to add the necessary dependencies and make some adjustments. Run the following commands:
Next, create a .babelrc.js
file in the root directory with the following:
Change your package.json
and add the following script to build the addon:
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.
Now let’s add a panel to Storybook. Inside the src
directory, create a new file called register.js
and add the following:
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:
panel
titled My Addon
to the UIpanel
renders the static div
contentFinally, let’s hook it all up. Change .storybook/main.js
to the following:
register.js
or preset.js
as the entry points.Run yarn storybook
and you should see something similar to:
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.
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:
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.
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.json
file with metadata about the addonreact
and @storybook/addons
preset.js
file at the root level written as an ES5 modulesrc
directory containing the ES6 addon codedist
directory containing transpiled ES5 code on publishReference 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 Learn Storybook’s “creating addons” tutorial. It’s an excellent walkthrough that covers the same ground as the above introduction, but goes further and leads you through the full process of creating a realistic addon.
How to build a Storybook addon shows you how to create a standalone addon in great detail.
To help you jumpstart the addon development, the Storybook maintainers created some dev-kits
, use them as reference when building your next addon.