storybook/docs/migration-guide.md

title
Migration guide for Storybook 8.0

Storybook 8 focuses on performance and stability.

• 💨 2-4x faster test builds, 25-50% faster React docgen, and SWC support for Webpack projects
• ✨ Improved framework support: you no longer need to install React as a peer dependency when using a non-React renderer
• 🌐 Support for React Server Components (RSC): our experimental solution renders async RSC in the browser and mocks Node code
• ➕ Much, much more

This guide is meant to help you upgrade from Storybook 7.x to 8.0 successfully!

ℹ️ Migrating from Storybook 6.x?

We recommend first upgrading to Storybook 7, then upgrading to Storybook 8.

To upgrade your project to Storybook 7, run:

npx storybook@^7 upgrade

Then reference the Storybook 7 migration guide to ensure you address any relevant breaking changes or manual migrations.

Major breaking changes

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

• storiesOf API has been removed
• *.stories.mdx format has been removed
• Implicit actions (from argTypesRegex) can no longer be used during rendering (e.g. in a play function)
• react-docgen (instead of react-docgen-typescript) is the default for component analysis
• Yarn 1 is no longer supported
• Node 16 is no longer supported
• Storyshots has been removed
• Addons API introduced in Storybook 7 is now required

If any of these apply to your project, please read through the full migration notes before continuing. If any of these new requirements or changes do not fit your project, you should probably stick with Storybook 7.x.

Automatic upgrade

To upgrade your Storybook:

<CodeSnippets paths={[ 'common/storybook-upgrade.npm.js.mdx', 'common/storybook-upgrade.pnpm.js.mdx', 'common/storybook-upgrade.yarn.js.mdx' ]} />

This will:

1. Upgrade your Storybook dependencies to the latest version
2. 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 on your behalf

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

<CodeSnippets paths={[ 'common/init-command.npx.js.mdx', 'common/init-command.pnpm.js.mdx', 'common/init-command.yarn.js.mdx' ]} />

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 8 and auto-configure it to mirror project settings

Manual migrations

In addition to the automated upgrades above, there are manual migrations that might be required to get Storybook 8 working in your project. We’ve tried to minimize this list to make it easier to upgrade. These include:

storiesOf to CSF

Storybook architecture is focused on performance and now needs code that is statically analyzable. For that reason, it does not work with storiesOf. We provide a codemod which, in most cases, should automatically make the code changes for you (make sure to update the glob to fit your files):

# Convert storiesOf to CSF
npx storybook@latest migrate storiesof-to-csf --glob="**/*.stories.tsx" --parser=tsx

Then, you can optionally convert CSF 2 to CSF 3 (why should you do this?):

# Convert CSF 2 to CSF 3
npx storybook@latest migrate csf-2-to-3 --glob="**/*.stories.tsx" --parser=tsx

storiesOf to dynamically created stories

If you are using storiesOf for its ability to dynamically create stories, you can build your own "storiesOf" implementation by leveraging the new (experimental) indexer API. A proof of concept of such an implementation can be seen in this StackBlitz demo. See the demo's README.md for a deeper explanation of the implementation.

*.stories.mdx to MDX+CSF

Storybook now requires that MDX pages now reference stories written in CSF, rather than the previous .stories.mdx hybrid approach. You can automatically convert your files using the following codemod (make sure to update the glob to fit your files):

npx storybook@latest migrate mdx-to-csf --glob "src/**/*.stories.mdx"

You’ll also need to update your stories glob in .storybook/main.js to include the newly created .mdx and .stories.js files if it doesn’t already.

Note: this migration supports the Storybook 6 “CSF stories with MDX docs” recipe.

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. If you’re running storybook with the dev command, try using the build command instead. Sometimes build errors are more legible than dev errors!
2. Check the full migration notes, which contains an exhaustive list of noteworthy changes in Storybook 8. 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.
3. 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.
4. If there’s no existing issue, you can file one, ideally with a reproduction attached. We’ll be on top of Storybook 8 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. Community addons that work well with 7.x might not yet be compatible with 8.0, and this is the fastest way to isolate that possibility. If you find an addon that needs to be upgraded to work with Storybook 8, please post an issue on the addon’s repository, or better yet, a PR 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 8.0.0-beta.56, you could set the version to 7.0.0-alpha.0 in your package.json and reinstall to verify that it still works (alpha.0 should be nearly identical to 7.6.x). If it works, you could then try 7.0.0-beta.0, then 7.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 PR to the Storybook repo and we’ll do our best to take care of it quickly.

Optional migrations

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

These include:

• TK