Migration guide for Storybook 11

Storybook 11 is agent-ready for React, Vue, Angular, Web Components, Svelte:

• 🏗️ Automated setup and upgrade
• 🧠 Optimized docgen and code examples
• ✅ Typesafe stories
• 🧪 Fast component testing
• 👀 Agentic UI review

Browse the changelog for the full list of changes.

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

For most projects, the migration has four steps:

1. Check that your project meets the new requirements.
2. Run the upgrade command. It updates your dependencies and runs automigrations for most configuration changes.
3. Make the manual changes that apply to your project. Each one depends on a feature you may not use, so skip the ones that don't apply.
4. Consider optional migration steps. These will help you take advantage of new features and improvements in Storybook 11.

If you maintain an addon, also read the addon migration guide.

Before you upgrade

Check the minimum versions

Storybook 11 raises these minimum versions. Upgrade any that apply before you upgrade Storybook.

For the framework-specific details, see the full migration notes.

TypeScript

typescript is now a required peer dependency of the React, Vue 3, Svelte, and Web Components renderers and frameworks. This applies to JavaScript projects too (typescript will be installed, but does not need to be used for compiling). This is because server-side docgen uses TypeScript to read the JSDoc and type annotations in your components.

Additionally, the latest version of TypeScript, 7.0, does not include the compiler API that Storybook uses to generate Controls and the args table. Therefore, Storybook cannot use TypeScript 7 for these purposes and requires TypeScript 5.9 or 6.x.

Package managers vary in their peer dependency handling. Yarn does not install a missing peer dependency. npm and pnpm do, but they install TypeScript 7, which docgen cannot use.

If your project has no typescript dependency, run this command to add typescript@^6 for you:

npx storybook@next automigrate typescript-dependency

To use TypeScript 6 for Storybook while keeping TypeScript 7 for tsc (i.e. for your app), point the typescript package at TypeScript 6:

{
  "devDependencies": {
    "@typescript/native": "npm:typescript@^7.0.2",
    "typescript": "npm:@typescript/typescript6@^6.0.2"
  }
}

See TypeScript 7 configuration for details.

Check for removed support

Storybook 11 removes support for the following setups. If your project is impacted, switch before you upgrade:

• Create React App preset. @storybook/preset-create-react-app is no longer published, and the upgrade stops while it is installed. Use @storybook/react-vite instead. See the Create React App notes.
• Yarn Plug'n'Play. Set nodeLinker: node-modules in .yarnrc.yml and run yarn install. See the Yarn PnP notes.
• Some community addons and builders. Packages that import storybook/internal/babel stop loading until they publish a release for Storybook 11. Check the list of affected packages.

If any of these requirements block your project, we recommend that you keep using Storybook 10.x.

Automatic upgrade

To upgrade your Storybook, run the upgrade command in the root of your repository:

npx storybook@next upgrade

This will:

1. Find all of the Storybook projects in your repository
2. For each project
   1. Determine that none of the blocking requirements 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

Automigrations

These automigrations are new in Storybook 11. To run one again later, use npx storybook automigrate <id>.

An automigration stops when it cannot safely edit a file. It then prints instructions for you to make the necessary changes manually, and lists affected files in automigrations-summary.md.

What changes after you upgrade

These changes need no action, but can affect your project.

Server-side docgen is on by default

Storybook 11 reads your components' props on the Storybook server with the TypeScript compiler API. This data is then used to generate manifests, Controls, story snippets, and code panels.

This docgenServer feature is on by default for these frameworks:

• @storybook/angular-vite
• @storybook/nextjs
• @storybook/nextjs-vite
• @storybook/react-native-web-vite
• @storybook/react-vite
• @storybook/react-webpack5
• @storybook/svelte-vite
• @storybook/sveltekit
• @storybook/tanstack-react
• @storybook/vue3-vite
• @storybook/web-components-vite

It replaces React's typescript.reactDocgen and Vue's framework.options.docgen.

Check your Controls panel, docs pages, and args tables after you upgrade:

• Story snippets and the code panel are static and do not update after changing controls. Dynamic snippets are expected in Storybook 11.1.
• Builder docgen options such as propFilter have no server-side equivalent. Unlike before, we now read prop types from node_modules by default, but we have heuristics in place to avoid picking up unnecessary types.
• React props come from TypeScript types. Defaults come from destructuring and defaultProps, with destructuring taking precedence. Storybook no longer reads propTypes, so a component that declares props only with propTypes shows no props.
• Web Components event, slot, and part argType keys get a suffix, such as my-change-event. See Manual migrations.
• Svelte Snippet and callback props move to the slots and events categories.

To keep builder docgen, set features.docgenServer: false in .storybook/main.js|ts. Builder docgen is deprecated and will be removed in Storybook 12.

Other changed defaults

• storybook dev no longer opens a browser. It prints the local URL. To open a browser, add --open to your storybook dev script, or set "open": true in the Angular builder options.
• The Code panel is on. With @storybook/addon-docs installed, every story has a Code panel. To hide it, set parameters.docs.codePanel to false in .storybook/preview.js|ts.
• Change detection and agentic review are always on. In storybook dev, the sidebar shows new and modified stories and the Review button. You can no longer turn them off.
• Standalone docs pages are single sidebar entries. An MDX page that is not attached to a component is no longer wrapped in a component with one Docs child. If your sidebar.renderLabel function or sidebar filters read that wrapper, see the sidebar notes.

Manual migrations

The upgrade cannot make these changes for you. Each row starts with the condition that makes it apply. If none apply, your migration is done.

Configuration

Rows are grouped by where the change happens: .storybook/main, .storybook/preview, .storybook/manager, then the CLI.

Stories and tests

Frameworks

Next.js (Webpack-only)

If a story or component imports a Node.js built-in such as path or url, storybook build now fails with Module not found. Remove the import, or add a browser polyfill in webpackFinal. See the Next.js polyfill notes.

Angular

With @storybook/angular-vite, BrowserAnimationsModule and NoopAnimationsModule in moduleMetadata.imports are no longer converted for you. Add provideAnimations() or provideNoopAnimations() to the providers of the applicationConfig decorator. See the Angular animation notes.

Svelte and SvelteKit

• Svelte CSF supports only stories defined with defineMeta (Svelte CSF 3) or preview.meta (Svelte CSF 4). The automigration lists files that use <Meta>, <Template>, let:args, or the id, autodocs, and source props on <Story>. Migrate them by hand with the Svelte CSF notes.
• If a stories file needs a preprocessor outside of <style>, for example for TypeScript enums, move that code to a separate module. See the indexing notes.
• With SvelteKit 3, replace $app/stores with $app/state, and parameters.sveltekit_experimental.stores with parameters.sveltekit_experimental.state. See the SvelteKit notes.

Web Components

• Add the category suffix to argTypes keys for events, slots, and CSS parts, for example my-change-event instead of my-change. Custom render functions read the same suffixed keys. See the argType key notes.
• Stories without a render function no longer log events by themselves. Pass fn() as the <name>-event arg for each event you want in the Actions panel. See the default render notes.
• If you use @wc-toolkit/storybook-helpers, remove it. Storybook now does the same work. See the @wc-toolkit/storybook-helpers notes.

Custom tooling

If you build tools on storybook/internal/* entry points, read the internal tooling notes. storybook/internal/babel is removed, csf-tools uses ESTree nodes, and several internal APIs changed or became private.

Optional migrations

These migrations are not required to upgrade. They move your project off formats and features that Storybook 11 still supports but no longer recommends.

CSF 3 to CSF 4

CSF 4 (previously called CSF Next) has better type safety with less boilerplate and is the recommended story format in Storybook 11. Your CSF 3 stories still work, and you can upgrade one file at a time. CSF 4 is available for React, Vue, Angular, Web Components, and Svelte.

To upgrade all of your CSF 3 stories automatically, run:

npx storybook automigrate csf-factories

For monorepos and manual upgrade steps, see Upgrade to CSF 4.

Builder docgen to server-side docgen

Builder docgen is deprecated. This covers React's react-docgen and react-docgen-typescript, the Vue 3 Vite docgen option, and the Svelte docgen option. It runs when you set features.docgenServer: false, and Storybook then prints a deprecation warning. React projects on TypeScript 7.0 also fall back to it until Storybook supports TypeScript 7.1. Remove that setting to use server-side docgen. React no longer installs the builder docgen packages: if you keep docgenServer: false, add react-docgen (or, for typescript.reactDocgen: 'react-docgen-typescript', the plugin for your builder and react-docgen-typescript) to your devDependencies, or Storybook stops with the install command. See the builder docgen notes.

angular-vite projects may opt-in to server-side docgen by setting features.experimentalDocgenServer: true in .storybook/main.js|ts. For more details, see the framework documentation.

Next.js Webpack to Next.js Vite

The Webpack-based @storybook/nextjs framework is deprecated. Follow the instructions to migrate to @storybook/nextjs-vite, or run npx storybook automigrate nextjs-to-nextjs-vite. The automigration does not change webpackFinal, so move any custom Webpack configuration to viteFinal yourself. Also add Vite's ?raw suffix to direct .md imports.

Web Components runtime manifest API to customElementsManifest

setCustomElementsManifest() and setCustomElements() are deprecated. With server-side docgen, Storybook reads your elements from your source files, so you can remove the call from .storybook/preview.js|ts. To keep a manifest you generate yourself, set its path in framework.options.customElementsManifest in .storybook/main.js|ts. The web-components-runtime-manifest automigration does both for you. See the Web Components manifest notes.

test-runner to addon-vitest

Official support for the test-runner has ended. It still runs with Storybook 11, but it no longer receives fixes or compatibility updates. Follow the instructions to migrate to addon-vitest. If your project uses a Webpack-based framework, the test runner notes explain how to switch to Vite first.

New projects

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

npm create storybook@next

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 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, 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. 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, 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. Check the packages known to need a release. 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 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.