Upgrading Storybook

The frontend ecosystem is a fast-moving place. Regular dependency upgrades are a way of life, whether upgrading a framework, library, tooling, or all of the above! Storybook provides a few resources to help ease the pain of upgrading.

Upgrade script

The most common upgrade is Storybook itself. Storybook releases follow Semantic Versioning. We publish patch releases with bug fixes continuously, minor versions of Storybook with new features every few months, and major versions of Storybook with breaking changes roughly once per year.

To help ease the pain of keeping Storybook up-to-date, we provide a command-line script that automatically detects all Storybook projects in your repository:

npx storybook@latest upgrade

Important: Always run the upgrade command from your repository root. The script will automatically detect all Storybook projects in your repository, including in mono-repository setups.

The upgrade command will use whichever version you specify. For example:

storybook@latest upgrade will upgrade to the latest version
storybook@8.6.1 upgrade will upgrade to 8.6.1
storybook@9 upgrade will upgrade to the newest 9.x.x version

The upgrade command is designed to upgrade from one major version to the next.

✅ OK: Using Storybook 8 and running storybook@9 upgrade
❌ Not OK: Using Storybook 7 and running storybook@9 upgrade

If you want to upgrade across more than major version, run the command multiple times. For example, to upgrade from Storybook 7 to Storybook 9, you first need to upgrade to the latest version of Storybook 8 with storybook@8 upgrade, and then run storybook@9 upgrade to upgrade to the latest version of Storybook 9.

The only exception to this is when upgrading from 6 to 8, where you can run storybook@8 upgrade directly to upgrade from 6.x.x to 8.x.x.

Mono-repository support

The upgrade script provides enhanced support for mono-repositories:

Automatic detection: The script automatically detects all Storybook projects in your repository
Selective upgrades: If your Storybooks are truly encapsulated (meaning each Storybook project has its own independent Storybook dependencies in its own package.json), you can select which Storybook project to upgrade
Bulk upgrades: If your Storybooks share dependencies, all detected projects will be upgraded together to ensure consistency

Limiting scope in large mono-repositories

For large mono-repositories where you want to limit the upgrade to a specific directory, use the STORYBOOK_PROJECT_ROOT environment variable:

STORYBOOK_PROJECT_ROOT=./packages/frontend storybook@latest upgrade

This is especially helpful in huge mono-repositories with semi-encapsulated Storybooks.

Upgrade process

After running the command, the script will:

Detect all Storybook projects in your repository
Upgrade all Storybook packages to the specified version
Run the relevant automigrations factoring in the breaking changes between your current version and the specified version
Automatically run the doctor command to verify the upgrade

In addition to running the command, we also recommend checking the MIGRATION.md file, for the detailed log of relevant changes and deprecations that might affect your upgrade.

Automatic health check

The upgrade script automatically runs a health check on all detected Storybook projects after the upgrade. This verifies that the upgrade was completed successfully and checks for common issues that might arise after an upgrade, such as duplicated dependencies, incompatible addons, or mismatched versions.

The health check runs automatically for all detected Storybooks. You can also run it manually at any time using the storybook doctor command:

npx storybook@latest doctor

Error handling and debugging

If you encounter issues during the upgrade:

A debug-storybook.log file will be created in the repository root containing all relevant logs
For more detailed information, set the log level to debug using the --loglevel debug flag
Create a GitHub issue with the logs if you need help resolving the problem

Command-line options

The upgrade command supports several flags to customize the upgrade process:

storybook@latest upgrade [options]

Available flags

Flag	Description
`-c, --config-dir <dir-name...>`	Directory or directories to find Storybook configurations
`--debug`	Enable more logs for debugging (default: false)
`--disable-telemetry`	Disable sending telemetry data
`--enable-crash-reports`	Enable sending crash reports to telemetry data
`-f, --force`	Force the upgrade, skipping autoblockers
`--loglevel <level>`	Define log level: `debug`, `error`, `info`, `silent`, `trace`, or `warn` (default: `info`)
`--package-manager <manager>`	Force package manager: `npm`, `pnpm`, `yarn1`, `yarn2`, or `bun`
`-s, --skip-check`	Skip postinstall version and automigration checks
`--write-logs`	Write all debug logs to a file at the end of the run
`-y, --yes`	Skip prompting the user

Example usage

# Upgrade with logging for debugging
storybook@latest upgrade --loglevel debug --write-logs
 
# Force upgrade without prompts
storybook@latest upgrade --force --yes
 
# Upgrade specific config directories only
storybook@latest upgrade --config-dir .storybook-app .storybook-ui

Automigrate script

Storybook upgrades are not the only thing to consider: changes in the ecosystem also present challenges. For example well-known frontend frameworks, such as Angular, Next.js or Svelte have been rolling out significant changes to their ecosystem, so even if you don't upgrade your Storybook version, you might need to update your configuration accordingly. That's what Automigrate is for:

npx storybook@latest automigrate

It runs a set of standard configuration checks, explains what is potentially out-of-date, and offers to fix it for you automatically. It also points to the relevant documentation so you can learn more. It runs automatically as part of storybook upgrade command, but it's also available on its own if you don't want to upgrade Storybook.

Prereleases

In addition to the above, Storybook is under constant development, and we publish pre-release versions almost daily. Pre-releases are the best way to try out new features before they are generally available, and we do our best to keep them as stable as possible, although this is not always possible.

To upgrade to the latest pre-release:

npx storybook@next upgrade

The upgrade command will use whichever version you specify. For example:

storybook@next upgrade will upgrade to the newest pre-release version
storybook@8.0.0-beta.1 upgrade will upgrade to 8.0.0-beta.1
storybook@8 upgrade will upgrade to the newest 8.x version

If you'd like to downgrade to a stable version, manually edit the package version numbers in your package.json and re-install.

Storybook collects completely anonymous data to help us improve user experience. Participation is optional, and you may opt-out if you'd not like to share any information.

Troubleshooting

Storybook doesn't detect my Storybook project

By default, the upgrade script will attempt to find Storybook configuration in .storybook directories in your repository. If your Storybook configuration is located in a different directory, you can specify it using the --config-dir flag.

The --config-dir flag can accept multiple directories.

storybook@latest upgrade --config-dir .storybook-app .storybook-ui

If your project can be detected, but you get an error during the detection process, please check the debug-storybook.log file in the root of your repository. It will contain the full output of the detection process and will help you troubleshoot the issue.

Storybook doesn't automigrate non-Storybook files

Our automigrations usually only transform and migrate files inside of your .storybook directory and your story and mdx files, which are mentioned as part of the Storybook configuration.

If you have other files that contain Storybook-specific code, you might need to manually migrate them.