Addon migration guide for Storybook 9.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 9.0, bringing new features and improvements, this guide is here to assist you in migrating your addons from 8.x to 9.0. If you need to migrate your addon from an earlier version of Storybook, please first refer to the Addon migration guide for Storybook 8.0.

Replacing dependencies

Many previously-published packages have moved to be part of Storybook's core. If your addon depends on any of these packages, you should remove them from your package.json and update your addon to import from the new location. If your addon does not already depend on the storybook package, you should add it to your package.json as a dependency.

{
  "devDependencies": {
    "storybook": "next" // or "latest", or "^9.0.0"
  }
}

Dependency Management

With Storybook 9.0, most Storybook packages have been consolidated into the main storybook package. This means you no longer need to reference individual Storybook packages as dependencies. Instead, define storybook as a peer dependency in your addon's package.json:

{
  "name": "your-storybook-addon",
  "peerDependencies": {
    "storybook": "^9.0.0"
  },
  "devDependencies": {
    "storybook": ">=9.0.0-0 <10.0.0-0" // For local development
  }
}

This approach ensures that:

1. Your addon uses the same version of Storybook APIs as the host project
2. You avoid duplicate Storybook packages in the final bundle
3. Your addon's package size is minimized

If your addon supports multiple major versions of Storybook, you can specify a wider version range in your peer dependencies:

{
  "name": "your-storybook-addon",
  "peerDependencies": {
    "storybook": "^8.0.0 || ^9.0.0"
  },
  "devDependencies": {
    "storybook": ">=9.0.0-0 <10.0.0-0" // For local development
  }
}

However, we recommend releasing a new major version of your addon alongside new major versions of Storybook. This practice:

1. Makes it easier to maintain your code
2. Allows you to take advantage of new features and improvements
3. Provides a clearer upgrade path for your users

Key changes for addons

Here are the essential changes in version 9.0 that impact addon development.

Package Consolidation

Several packages have been consolidated into the main storybook package. Update your imports to use the new paths:

Additionally, several internal packages have been moved under the /internal sub-path. These paths are not part of our public API, so they may change without following semver. While you can use them for a quick upgrade, we strongly encourage finding replacements as they could break in future minor versions:

Please visit the full list of consolidated packages in our Migration.md file.

Icon System Updates

The icon system has been updated to use @storybook/icons. Several icon-related exports have been removed:

- import { Icons, IconButtonSkeleton } from '@storybook/components';
+ import { ZoomIcon } from '@storybook/icons';

Manager Builder Changes

The manager builder no longer aliases util, assert, and process. If your addon depends on these packages, you'll need to:

1. Implement the alias at compile time in your addon
2. Update your bundling configuration to ensure correct dependencies are used

Node.js 18 support dropped

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

TypeScript Requirements

Storybook now requires TypeScript 4.9 or later. Ensure your addon is compatible with this version.

Sidebar Component Changes

1. The 'extra' prop has been removed from the Sidebar's Heading component
2. Experimental sidebar features have been removed:
   • experimental_SIDEBAR_BOTTOM
   • experimental_SIDEBAR_TOP

Type System Updates

The following types have been removed:

• Addon_SidebarBottomType
• Addon_SidebarTopType
• DeprecatedState

9.0.0 Full migration guide

For a full list of changes, please visit the Migration.md file

Migration Example

For a complete example of an addon updated to support Storybook 9.0, refer to the Addon Kit migration PR. Once merged, it will demonstrate all the necessary changes for modern addon development.

Releasing

To support Storybook 9.0, we encourage you to release a new major version of your addon. For experimental features or testing, use the next tag. This allows you to gather feedback before releasing a stable version.

Support

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