Addon migration guide for Storybook 8.0

We sincerely appreciate the dedication and effort addon creators put into keeping the Storybook ecosystem vibrant and up-to-date. As Storybook evolves to version 8.0, bringing new features and improvements, this guide is here to assist you in migrating your addons from 7.x to 8.0. If you need to migrate your addon from an earlier version of Storybook, please first refer to the Addon migration guide for Storybook 7.0.

As we gather feedback from the community, we’ll update this page. We also have a general Storybook migration guide if you’re looking for that.

Updating dependencies

Begin by updating your Storybook dependencies. Use the next tag for pre-release versions, latest for the most recent stable release, or specify the version directly.

{
  "dependencies": {
    "@storybook/client-logger": "next" // or "latest", or "^8.0.0"
  }
}

Key changes for addons

Here are the essential changes in version 8.0 that impact addon development. Please check the complete migration note for an exhaustive list of changes in 8.0.

Node.js 16 support dropped

Please upgrade your addon to Node.js 18, as support for Node.js 16 has ended.

React 18 for manager UI

UI-based addons (e.g., panels, toolbars, tabs) rely on React 18 to render their elements in the Storybook UI. Also, note that the key prop is no longer passed to the render function.

React peer dependency is no longer required

To remove your addon's peer dependency on React and reduce its install size, do the following:

Move react, react-dom, and the globalized Storybook packages from peerDependencies to devDependencies
Add the list of globalized packages to the externals property in the tsup configuration to ensure they are not part of the bundle.

For an example, see the updates we've made to the Addon Kit. These changes are optional but recommended.

This assumes your addon uses tsup for bundling. If your addon was built with an older version of the Addon Kit that uses Babel for bundling, you must first switch to tsup. For guidance, explore these older changes implemented in the Addon Kit repository.

@storybook/components deprecations

The Icons component from @storybook/components is now deprecated in favor of @storybook/icons. Additionally, various Button component props are also deprecated, with alternatives provided.

Storybook layout state API changes

If you're customizing the Storybook UI configuration with addons.setConfig({...}), be aware of the changes to the layout state API.

Removal of deprecated features

Deprecated packages and APIs from 7.0 are now removed in 8.0. Consult the full migration notes for details. Most notably, for addons, the removal of the @storybook/addons package requires you to switch to @storybook/preview-api and @storybook/manager-api for the same functionality.

Babel-loader removed from Webpack

Storybook 8 removes babel-loader from the webpack5 builder. If your addon's preset overrides the babel() method, it will break if your users are using SWC to compile their files (which is the new default for Webpack 5-based Storybook projects).

To ensure your addon supports both Babel and SWC, you can build a custom bundling plugin using Unplugin that will work with both Webpack and Vite builders, giving you complete control to run Babel (or whatever you want) on stories and components as they are loaded.

As a workaround, update your documentation to tell users to opt-in to Babel support. This should fix your addon in their project at the cost of performance:

npx storybook@latest add @storybook/addon-webpack5-compiler-babel

Migration Example

The Addon Kit repository has already been updated to support Storybook 8.0, and you can use it as a reference for your migration. You'll see the changes mentioned in this guide, including ESM support via the type: module configuration. As an addon maintainer, we encourage you to update your addon to include them. It simplifies the setup and makes it easier for users to use your addon with the latest version of Storybook. If you choose to follow along with the ESM migration, we've prepared an abbreviated list of changes below.

package.json for dependency management, ESM support and updates to the addon's entry points.
tsup.config.ts for bundling changes, factoring in Storybook's globals.
.storybook/local-preset.js to support the ESM migration.

For a complete overview of the changes applied to the Addon Kit to fully support Storybook 8.0, see the following diff view.

Releasing

To support Storybook 8.0, we encourage you to release a new major version of your addon and continue supporting 7.x with minor or patch versions. For experimental features or testing, opt for the next tag. This will allow you to test your addon in projects and gather feedback before releasing a stable version.

Support

If you're still having issues with your addon after following this guide, please open a new discussion in our GitHub repository.