Should I upgrade to Storybook 9 Upgrade and Addon API Breaking Changes in now?

Decide whether to upgrade to Storybook 9 now or defer, given addon API breakage, package reshuffling, and the maintenance cost of staying on older Storybook lines.

Defer on Storybook 8 and pin the latest 8.x minor unless your addon surface is already 9-compatible; only upgrade now when migration work is clearly cheaper than waiting.

Blockers

Who this is for

Candidates

Upgrade to Storybook 9 now and budget addon migration work

Storybook's official migration guide from 8.x to 9.1 says Storybook 9 brings major breaking changes, including package consolidation, essential addons moving into core, a renamed test addon, and higher ecosystem minimums. As of 2026-03-29, the migration guide says Node 20+, Vite 5+, Vitest 3+, TypeScript 4.9+, npm 10+, pnpm 9+, and yarn 4+ are required, with framework floors such as Next.js 14+, Angular 18+, Lit 3+, and Svelte 5+. The addon migration guide says most Storybook packages are consolidated into the main "storybook" package and addon authors should use "storybook" as a peer dependency for 9.x. Storybook's official upgrade command and automigrations exist, but the docs explicitly warn that community addons that worked on 8.x may not yet be compatible with 9.x.

When to choose

Use this when your repo already meets the new runtime and framework floors and you can touch internal or third-party addons now. The decisive factor is whether addon compatibility work is cheaper than continuing on an older line with only limited backported fixes.

Tradeoffs

You get the supported 9.x API shape, lighter package structure, and migration tooling, but you take immediate addon breakage risk and may need import rewrites plus peer dependency updates.

Cautions

Official docs say several internal packages only continue to work through 9.x via "storybook/internal/*" and are likely removed in 10.0, so a quick compatibility patch that leans on internal paths can create another forced migration soon after. Webpack builder support was removed for Preact, Vue, and Web Components in favor of Vite.

Sources

Defer on Storybook 8 temporarily and pin the latest 8.x minor

Storybook's release policy says that as of 2026-03-29 the project actively maintains 10.x, while 9.x and 8.x receive backports only for High or Critical security fixes and only on the latest minor. The 9.x migration guide explicitly says that if the new requirements or changes are blockers, teams should continue using Storybook 8.x. This makes short deferral a viable option if your addon surface is large or your toolchain is below Node 20, Vite 5, or the newer framework minimums. The maintenance cost is that you are staying on a line that is no longer the actively maintained major and you still owe the package and addon API migration later.

When to choose

Use this when addon compatibility is the real blocker and you need a controlled delay rather than an immediate migration. The decisive factor is whether you can keep risk acceptable by pinning the latest 8.x minor and avoiding net-new Storybook customization.

Tradeoffs

This lowers near-term delivery risk, but you accept reduced support scope, delayed package cleanup, and a larger future jump if more ecosystem changes pile up.

Cautions

Do not treat 8.x as fully maintained; official policy only promises High or Critical security backports to the latest 8.x minor. Any custom addon code still tied to older package layouts will remain migration debt.

Sources

Skip 9 as a landing zone and plan a direct move to Storybook 10

Storybook's release policy says 10.x is the actively maintained major as of 2026-03-29, with 9.x and 8.x limited to security backports on their latest minors. If you are already doing a wider platform refresh, moving first to 9 can be an extra transitional step because Storybook 9's docs mark several internal package replacements as likely removed in 10.0. The practical case for skipping 9 is strongest when your current Storybook usage is light and your addon estate is mostly under your control. Check official docs for exact 10.x migration requirements before committing, because this card only verifies the support policy and the 9.x-to-10.0 removal warning.

When to choose

Use this when you are already budgeting a broader Node, package-manager, builder, or framework upgrade and do not want two consecutive Storybook migrations. The decisive factor is whether you can test your addon surface directly against the current major instead of spending effort on 9-specific compatibility.

Tradeoffs

You avoid a temporary landing zone, but you take on a larger single migration and need to validate against the current major's docs rather than relying on 9.x compatibility.

Cautions

This is not the low-risk path for teams with many external community addons, because the 9.x guide already flags addon compatibility issues and internal API churn. Verify current 10.x migration notes in official docs before execution.

Sources

Facts updated: 2026-03-29
Published: 2026-04-03

Related questions

Try with your AI agent

$ npm install -g pocketlantern
$ pocketlantern init
# Restart Claude Code, Cursor, or your MCP client, then ask:
# "Should I upgrade to Storybook 9 Upgrade and Addon API Breaking Changes in now?"
Missing something? Request coverage