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:
- Upgrading the Storybook packages
- Dealing with breaking changes
- 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 upgrade
Then try running 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-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-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.
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_modulesand your lockfile and reinstalling.
yarnoccasionally need an extra kick in the pants!
🤟 Step 3: Best practices
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.
✴️ Do you use TypeScript? If so, upgrade to our new zero config Typescript setup for improved performance and better auto-generated documentation.
✴️ 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.
🖖 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:
- Search for your problem in our Github issues — somebody else might have run into the same problem.
- Create a new issue describing your problem, ideally with a link to a public repo where we can reproduce the issue.
- 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.