Upgrading and Migrations
Purpose and Scope
This page explains how Storybook’s release and migration documentation is organized for teams moving between major versions or replacing older testing infrastructure. The main release guide is written for upgrading a Storybook 9 project to Storybook 10, a breaking maintenance release centered on ESM-only package distribution, reduced install size, CSF Next preview improvements, and improved tag-based filtering. It also gives readers the decision points they need before running automation: check whether breaking changes apply, understand the supported path from older versions, and know when to pause rather than forcing an upgrade. Sources: docs/releases/migration-guide.mdx
Storybook treats upgrades as a workflow rather than a single package bump. The release guide first names the target version and the expected starting point, then calls out prerequisites and migration risks before introducing automation. That sequencing matters because the automatic upgrade can handle many common tasks, but it cannot remove every project-specific blocker. Readers should use this page to plan the upgrade order, decide whether their repository should move directly or in stages, and identify follow-up checks for broken development or build behavior after dependencies change. Sources: docs/releases/migration-guide.mdx
Relevant Source Files
- docs/releases/migration-guide.mdx — The Storybook 10 migration guide, including release goals, major breaking changes, automatic upgrade behavior, new project setup, and troubleshooting guidance.
- docs/writing-tests/integrations/vitest-addon/migration-guide.mdx — The testing migration guide for replacing the older test runner with the Vitest addon in eligible projects.
Release Migration Model
The Storybook 10 guide defines a staged path. Projects already on Storybook 9 can use the Storybook 10 migration guide directly. Projects earlier than Storybook 9 are instructed to upgrade to Storybook 9 first, then return to the Storybook 10 guide. This keeps the migration surface smaller and avoids mixing older breaking changes with the current ESM-only transition. The guide also explicitly recommends reading the linked full migration notes when a project is likely to hit a major breaking change or when automation cannot confidently proceed. Sources: docs/releases/migration-guide.mdx
The most important Storybook 10 compatibility checks called out by the guide are that the main configuration and other presets must be valid ESM, and that the runtime environment must satisfy the newer Node requirement. These are not cosmetic changes. A configuration file that still depends on CommonJS-only patterns can block startup, and an unsupported Node version can fail before Storybook reaches application code. The migration guide therefore places those constraints before the automatic upgrade section so teams can validate build agents, local developer machines, and custom presets early. Sources: docs/releases/migration-guide.mdx
Automatic Upgrade Flow
The automatic upgrade section describes the intended happy path. Run the documented upgrade command from the root of the repository so it can discover all Storybook projects. For each project, the upgrade process determines whether listed breaking changes apply, provides instructions if they do, upgrades Storybook dependencies to the latest version, and then runs automigrations. Those automigrations are described as checks for common upgrade tasks that explain necessary changes, link to more information, ask for approval, and then apply approved edits on the user’s behalf. Sources: docs/releases/migration-guide.mdx
For repositories with more than one Storybook configuration, the discovery behavior is an important operational detail. Running from the root lets the tooling find each Storybook project rather than only the current package. Teams should still treat the result as a reviewed change set: inspect dependency updates, review generated edits, and run both development and static build commands afterward. The troubleshooting section specifically suggests trying the build command when the development command produces unclear errors, because build failures may expose configuration or bundling problems with clearer output. Sources: docs/releases/migration-guide.mdx
New Projects and Version Adoption
The same migration guide also covers projects that are not currently using Storybook. Instead of upgrading an existing configuration, readers use the documented create flow. The guide says this creation process detects the project’s renderer, builder, or meta-framework, such as React, Vue, Angular, Web Components, Webpack, Vite, Next.js, or SvelteKit, then installs Storybook 10 and configures it to mirror project settings. This is useful during migration planning because some teams choose to validate Storybook 10 in a fresh project before changing a mature application. Sources: docs/releases/migration-guide.mdx
That new-project path is not a substitute for migrating a production Storybook. It creates a clean baseline that matches detected project technology, while the upgrade path preserves and transforms an existing Storybook setup. Use the new setup when adopting Storybook for the first time or creating a reference sandbox. Use the migration guide when a repository already has stories, addons, parameters, preview configuration, or custom builder behavior that needs to continue working after the version change. Sources: docs/releases/migration-guide.mdx
Testing Migration: Test Runner to Vitest Addon
The testing migration guide is narrower than the release migration guide, but it is part of the same upgrade planning surface because Storybook 9 and later emphasize a Vitest-based testing solution. It explains that the older test runner used Jest as the runner and Playwright as the browser environment, while the Vitest addon is a modern successor that runs stories as tests through Vitest and integrates with Storybook’s testing widget. The guide is explicit that teams do not have to change how stories are written when moving between these testing systems. Sources: docs/writing-tests/integrations/vitest-addon/migration-guide.mdx
Eligibility is the key constraint for the Vitest addon migration. The guide recommends the Vitest addon for React, Preact, Vue, Svelte, and Web Components projects that use the Vite builder, including Next.js with Vite. Projects using a different renderer, such as Angular, or using the Webpack builder are told to continue using the test runner. This prevents teams from treating the testing migration as universal. Before removing packages or files, confirm that the project’s renderer and builder match the supported set. Sources: docs/writing-tests/integrations/vitest-addon/migration-guide.mdx
Compact Migration Reference
| Area | Source-backed guidance |
|---|---|
| Storybook 10 target | Upgrade from Storybook 9.x to 10; earlier projects should first move to Storybook 9. |
| Key breaking requirements | Main configuration and presets must be valid ESM; newer Node versions are required. |
| Automation | Run the documented upgrade command at the repository root; it discovers projects, updates dependencies, and runs approved automigrations. |
| Troubleshooting | Use the doctor command for common issues, try a build for clearer failures, and consult full migration notes for unhandled edge cases. |
| New adoption | Use the documented create flow for projects not already using Storybook; it detects renderer, builder, or meta-framework. |
| Vitest addon migration | Remove the older test runner setup only for eligible Vite-based React, Preact, Vue, Svelte, or Web Components projects. |
The Vitest migration steps begin by removing package dependencies and then removing obsolete configuration files. The guide names the old test runner package, the optional coverage addon package, a Jest configuration file, and a Storybook test-runner configuration file. It also explains why those removals are safe in the supported path: accessibility is handled out of the box by the Vitest addon, and coverage uses Vitest’s built-in coverage support rather than separate instrumentation. Advanced custom hooks or image snapshot workflows require extra review rather than blind deletion. Sources: docs/writing-tests/integrations/vitest-addon/migration-guide.mdx
Next Steps
For a major release upgrade, begin with the Storybook 10 migration guide and verify the ESM and Node requirements before running automation. After the dependency update, run the doctor command, compare development and build failures, and review the full migration notes for changes not covered by automigrations. If the upgrade also changes the testing stack, read the Vitest addon migration guide separately and check renderer and builder eligibility first. Related pages for deeper work are CLI Options, Vite Builder, Writing Tests Overview, and Interaction Testing.