Storybook 6 Migration Guide

This step-by-step guide gets you upgraded to Storybook 6.0 (SB6).

Every year we release a major version of Storybook. Last Spring, that was Storybook 5.0, an incredible makeover of the user interface. This year, we’ve radically improved Storybook’s developer experience. We’ve turned it into a best-in-class documentation tool, and have completely overhauled configuration and story authoring in the process.

This guide takes you through:

1. Upgrading the Storybook packages
2. Dealing with breaking changes
3. Updating to current best practices

We assume you’re coming from a 5.0 project and tell you everything you need to know to upgrade. If you’ve been tracking the 5.x releases (5.1/5.2/5.3), you may be able to skip some steps. If you’re coming from an earlier version of Storybook you can refer to the SB5 upgrade guide and then come back.

☝️ Step 1: Package upgrade

The first thing to do is upgrade your Storybook packages, @storybook/*. You can do this with the following command:

npx sb@latest upgrade

Then try running Storybook:

yarn storybook

If the browser opens and things generally look OK, you’re most of the way there, and you can skip to Step 3.

✌️ Step 2: Breaking changes

If you don’t see your Storybook, it’s time to figure out which of the breaking changes tripped you up. This release is a semver major version, so it contains a number of possible gotchas.

Looking at the error/warning messages in your terminal AND in the browser console should give you clues into what went wrong.

In addition, here’s a checklist of common upgrade issues:

✅ Do you use TypeScript? It’s zero-config now — and much better! — but you’ll need to update your settings.

✅ Do you use hierarchy separators to control the sidebar navigation? We’ve simplified that in 6.0, and there’s a codemod to upgrade your stories.

✅ Do you use addon-info, addon-notes, addon-contexts, or addon-centered? If so, these have all been deprecated in 6.0.

✅ Do you use Create React App? If so, we’ve moved built-in CRA support into a separate package.

✅ Do you use addon-docs? We’ve removed framework-specific presets, separated the theming API from storybook’s main theming, removed the concept of “slots” for customization, renamed a few DocBlocks, and updated best practices for embedding CSF in MDX. See the Docs upgrade instructions for details.

✅ Do you use addon-actions, addon-backgrounds,addon-knobs, addon-links, or addon-queryparams? If so, we’ve added presets for each of these addons that improve the startup behavior for these addons, but may conflict with your existing settings. Read about it.

✅ Seeing core-js dependency errors? Here’s a workaround.

In addition to this high-level checklist, we’ve documented all the breaking changes and gotchas in exhaustive detail in our MIGRATION.md.

If you’ve run through this checklist and MIGRATION.md and are still getting an error, try clearing node_modules and your lockfile and reinstalling. npm/yarn occasionally need an extra kick in the pants!

🤟 Step 3: Best practices

If your Storybook is working now, congratulations! Give yourself a pat on the back. 🎉 If not, please check our Github issues or join us on Discord.

Now that you’ve got the basics out of the way, we also recommend you take some time to update your Storybook to the current best practices. None of this is strictly required, but it’s worth taking the time to do it now. Many of these changes will be required in SB7, and we’re actively improving and building upon the latest best practices.

These include:

✴️ Do you use storiesOf to write your stories? Upgrade to Component Story Format (CSF). Or choose MDX if you want more control over your documentation.

✴️ Do you use config.js to configure Storybook? Main.js declarative configuration, introduced in 5.3, is a huge improvement and the strong recommendation. Upgrade to main.js.

✴️ Do you use TypeScript? If so, upgrade to our new zero config Typescript setup for improved performance and better auto-generated documentation.

✴️ Want a curated, best-practice addon setup for your Storybook? Consider upgrading to Essentials, a major step towards a fully Zero-config Storybook.

✴️ Are your components documented? Add Storybook Docs to get auto-generated best practice documentation for all your stories.

✴️ Have a large storybook, want to document stories from multiple frameworks into a single Storybook, or otherwise need to combine multiple Storybooks into one? Upgrade to Storybook Composition.

✴️ Do you use addon-knobs? Storybook Controls is the no-code successor to Knobs that auto-generates the controls based on your component props. Here’s how to migrate your stories to controls.

✴️ Do you use global parameters or decorators? In 6.0 you should add them declaratively; we’ve deprecatedaddParameters/addDecorator.

🖖 Step 4: Live long and prosper

Hopefully at this point you’ve successfully upgraded to SB6. If so, congratulations and welcome to the world’s best way to develop, test, document, and explore your UI components!!! 🎉🎉🎉

If you had problems getting through this guide, or made it through the guide but still have problems, please take the following steps:

1. Search for your problem in our Github issues — somebody else might have run into the same problem.
2. Create a new issue describing your problem, ideally with a link to a public repo where we can reproduce the issue.
3. Join us in our public Discord and ask a question on the #support channel. We are a friendly community and want to help you get upgraded.