> **Version 9** — **React** / **TypeScript**
> Also available:
- `?codeOnly=true` for code snippets only
- other versions: Version 10.3 (latest) (`/docs/addons/addon-migration-guide.md`), Version 8 (`/docs/8/addons/addon-migration-guide.md`)

# 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](../../../release-8-6/docs/addons/addon-migration-guide.mdx).

  As we gather feedback from the community, we'll update this page. We also have a general [Storybook migration guide](../releases/migration-guide.mdx) if you're looking for that.

## Replacing dependencies

Many previously-published packages have [moved to be part of Storybook's core](../releases/migration-guide.mdx#package-structure-changes). 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.

```diff title="package.json"
{
  "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`:

```jsonc title="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:

```jsonc title="package.json"
{
  "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:

| Old Package                     | New Path                |
| ------------------------------- | ----------------------- |
| `@storybook/manager-api`        | `storybook/manager-api` |
| `@storybook/preview-api`        | `storybook/preview-api` |
| `@storybook/theming`            | `storybook/theming`     |
| `@storybook/test`               | `storybook/test`        |
| `@storybook/addon-actions`      | `storybook/actions`     |
| `@storybook/addon-backgrounds`  | N/A                     |
| `@storybook/addon-controls`     | N/A                     |
| `@storybook/addon-highlight`    | `storybook/highlight`   |
| `@storybook/addon-interactions` | N/A                     |
| `@storybook/addon-measure`      | N/A                     |
| `@storybook/addon-outline`      | N/A                     |
| `@storybook/addon-toolbars`     | N/A                     |
| `@storybook/addon-viewport`     | `storybook/viewport`    |

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:

| Old Package                  | New Path                             |
| ---------------------------- | ------------------------------------ |
| `@storybook/channels`        | `storybook/internal/channels`        |
| `@storybook/client-logger`   | `storybook/internal/client-logger`   |
| `@storybook/core-events`     | `storybook/internal/core-events`     |
| `@storybook/types`           | `storybook/internal/types`           |
| `@storybook/components`      | `storybook/internal/components`      |

Please visit the [full list of consolidated packages](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#dropped-support-for-legacy-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:

```diff
- 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](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-8x-to-900) file

## Migration Example

For a complete example of an addon updated to support Storybook 9.0, refer to the [Addon Kit migration PR](https://github.com/storybookjs/addon-kit/pull/75). 
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](https://github.com/storybookjs/storybook/discussions/new?category=migrations) in our GitHub repository.