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

# Migration guide for Storybook 11

[full-migration-notes]: https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-10x-to-1100

Storybook 11 is coming!

This guide is meant to help you **upgrade from Storybook 10.x to 11** successfully!

**Migrating from a Storybook version prior to 10?**

You'll first need to [upgrade to Storybook 10](https://storybook.js.org/docs/11/releases/migration-guide-from-older-version.md). Then you can return to this guide.

## Major breaking changes

The rest of this guide will help you upgrade successfully, either automatically or manually. But first, there are some [breaking changes][full-migration-notes] in Storybook 11. Here are the most impactful changes you should know about before you go further:

- Ecosystem updates
  - [Node.js 22.12 or higher](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#nodejs-2212-or-higher)
  - [Vite 6.3 or higher](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#vite-requires-vite-63-or-higher)
  - [Vitest 4 or higher for the Vitest addon](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#vitest-addon-requires-vitest-40-or-higher)
  - [Next.js 15 or higher](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#nextjs-require-v15-and-up)
  - [Angular 21 or higher](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#angular-requires-angular-21-or-higher)
  - [Create React App preset removed](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#create-react-app-support-removed)
  - [Yarn PnP support removed](#yarn-pnp-support-removed)
- Configuration changes
  - [Move top-level `setConfig` layout and UI options](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#top-level-setconfig-layout-and-ui-options-removed)
  - [Vite static asset copying and conflict precedence](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#vite-publicdir-is-handled-by-storybooks-staticdirs)
  - [Configure legacy Angular animations explicitly with Angular Vite](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#storybookangular-vite-legacy-animation-modules-are-no-longer-auto-converted)
- [Changes for addon authors](https://storybook.js.org/docs/11/addons/addon-migration-guide.md)

If any of these changes apply to your project, please read through the linked migration notes before continuing.

If any of these new requirements or changes are blockers for your project, we recommend to continue using Storybook 10.x.

You may wish to read the [full migration notes][full-migration-notes] before migrating. Or you can run the upgrade command below and we’ll try to take care of everything for you!

## Automatic upgrade

To upgrade your Storybook, run the [upgrade](https://storybook.js.org/docs/11/releases/upgrading.md) command in the root of your repository:

```shell
npx storybook@latest upgrade
```

```shell
pnpm dlx storybook@latest upgrade
```

```shell
yarn dlx storybook@latest upgrade
```

This will:

1. Find all of the Storybook projects in your repository
2. For each project
   1. Determine that none of the [breaking changes](#major-breaking-changes) apply to your project
      - If they do, you will receive instructions on how to resolve them before continuing
   2. Upgrade your Storybook dependencies to the latest version
   3. Run a collection of _automigrations_, which will:
      - Check for common upgrade tasks
      - Explain the necessary changes with links to more information
      - Ask for approval, then perform the task automatically on your behalf

## New projects

To add Storybook to a project that isn’t currently using Storybook:

```shell
npm create storybook@latest
```

```shell
pnpm create storybook@latest
```

```shell
yarn create storybook@latest
```

This will:

1. Figure out which renderer (React, Vue, Angular, Web Components), builder (Webpack, Vite), or meta-framework (Next.js, SvelteKit) you’re using
2. Install Storybook 11 and auto-configure it to mirror project settings

## Troubleshooting

The automatic upgrade should get your Storybook into a working state. If you encounter an error running Storybook after upgrading, here’s what to do:

1. Try running the [`doctor` command](https://storybook.js.org/docs/11/api/cli-options.md#doctor) to check for common issues (such as duplicate dependencies, incompatible addons, or mismatched versions) and see suggestions for fixing them.
2. If you’re running `storybook` with the `dev` command, try using the `build` command instead. Sometimes `build` errors are more legible than `dev` errors!
3. Check [the full migration notes][full-migration-notes], which contains an exhaustive list of noteworthy changes in Storybook 11. Many of these are already handled by automigrations when you upgrade, but not all are. It’s also possible that you’re experiencing a corner case that we’re not aware of.
4. Search [Storybook issues on GitHub](https://github.com/storybookjs/storybook/issues). If you’re seeing a problem, there’s a good chance other people are too. If so, upvote the issue, try out any workarounds described in the comments, and comment back if you have useful info to contribute.
5. If there’s no existing issue, you can [file one](https://github.com/storybookjs/storybook/issues/new/choose), ideally with a reproduction attached. We’ll be on top of Storybook 11 issues as we’re stabilizing the release.

If you prefer to debug yourself, here are a few useful things you can do to help narrow down the problem:

1. Try removing all addons that are not in the `@storybook` npm namespace (make sure you don't remove the `storybook` package). Community addons that work well with 10.x might not yet be compatible with 11.x, and this is the fastest way to isolate that possibility. If you find an addon that needs to be upgraded to work with Storybook 11, please post an issue on the addon’s repository, or better yet, a pull request to upgrade it!
2. Another debugging technique is to bisect to older prerelease versions of Storybook to figure out which release broke your Storybook. For example, assuming that the current prerelease of Storybook is `11.0.0-beta.56`, you could set the version to `11.0.0-alpha.0` in your `package.json` and reinstall to verify that it still works (`alpha.0` should be nearly identical to `10.6.x`). If it works, you could then try `11.0.0-beta.0`, then `11.0.0-beta.28` and so forth. Once you’ve isolated the bad release, read through its [CHANGELOG](https://github.com/storybookjs/storybook/blob/next/CHANGELOG.prerelease.md) entry and perhaps there’s a change that jumps out as the culprit. If you find the problem, please submit an issue or pull request to the Storybook monorepo and we’ll do our best to take care of it quickly.

## Yarn PnP support removed

Storybook 11 removes support for Yarn [Plug'n'Play](https://yarnpkg.com/features/pnp) (PnP), which was deprecated in Storybook 10:

- The `--use-pnp` flag no longer exists on the `storybook init` and `create storybook` commands.
- Storybook no longer bootstraps or scaffolds projects with Yarn PnP enabled. New projects always use the standard `node_modules` layout; if your project relies on Yarn PnP, switch your [`nodeLinker`](https://yarnpkg.com/features/linkers) setting to `node-modules`.
- The `detectPnp` utility is no longer exported from `storybook/internal/cli`.

For the configuration steps and removed CLI options, see the [Yarn PnP migration reference](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#yarn-pnp-support-removed).

## Optional migrations

In addition to the automigrations and manual migrations above, there are also optional migrations that you should consider. These are features that we’ve deprecated in Storybook 11 (but remain backwards compatible), or best practices that should help you be more productive in the future.

### Next.js Webpack to Next.js Vite

The Webpack-based `@storybook/nextjs` framework is deprecated but remains supported in Storybook 11. Its removal is planned for Storybook 12. Follow the [instructions to migrate to `@storybook/nextjs-vite`](https://storybook.js.org/docs/11/get-started/frameworks/nextjs-vite.md#how-do-i-migrate-from-the-nextjs-webpack-5-addon).

### `test-runner` to `addon-vitest`

`addon-vitest` and the rest of the [Storybook Test experience](https://storybook.js.org/blog/storybook-test-sneak-peek/) is designed to supercede the `test-runner`. It's faster and provides a better experience for writing and running tests. If your project is built with Vite and uses React, Vue, Angular, Web Components, or Svelte, you should consider following the [instructions to migrate to `addon-vitest`](https://storybook.js.org/docs/11/writing-tests/integrations/vitest-addon/migration-guide.md).