modernweb-dev · bashmish · Mar 6, 2026 · Mar 9, 2026 · Mar 9, 2026 · Mar 10, 2026
diff --git a/.changeset/shiny-sloths-drum.md b/.changeset/shiny-sloths-drum.md
@@ -0,0 +1,8 @@
+---
+'@web/storybook-addon-mocks': major
+'@web/storybook-builder': minor
+'@web/storybook-framework-web-components': minor
+'@web/storybook-utils': major
+---
+
+Migrate projects to Storybook 9
diff --git a/docs/docs/mocks/migration-to-storybook-9.md b/docs/docs/mocks/migration-to-storybook-9.md
@@ -0,0 +1,6 @@
+# Storybook Builder >> Migration from Storybook 8 to 9
+
+## General migration guide
+
+Storybook 9 introduced changes which consolidated external packages into the main Storybook packages. To avoid compatibility issues, `@web/mocks` won't be migrated and will keep support for Storybook 8, instead, we recommend using `@web/storybook-addons-mocks` which is compatible with Storybook 9.
+This is a drop-in replacement, so you can just change the import from `@web/mocks` to `@web/storybook-addons-mocks` and it should work without any issues while on version 9.
diff --git a/docs/docs/storybook-builder/migration-to-storybook-7.md b/docs/docs/storybook-builder/migration-to-storybook-7.md
@@ -1,4 +1,4 @@
-# Storybook Builder >> Migration to Storybook 7 ||5
+# Storybook Builder >> Migration to Storybook 7 ||6
 
 This guide explains how to migrate from [`@web/dev-server-storybook` plugin](../dev-server/plugins/storybook.md) (that used opinionated Storybook 6 bundle `@web/storybook-prebuilt`) to Storybook 7 and new `@web/storybook-builder`.
 

diff --git a/docs/docs/storybook-builder/migration-to-storybook-8.md b/docs/docs/storybook-builder/migration-to-storybook-8.md
@@ -1,4 +1,4 @@
-# Storybook Builder >> Migration from Storybook 7 to 8 ||4
+# Storybook Builder >> Migration from Storybook 7 to 8 ||5
 
 ## Update dependencies
 
@@ -11,7 +11,7 @@ You need to:
 
 ## General migration guide
 
-Make sure to follow the [Storybook's own migration guide](https://storybook.js.org/docs/migration-guide).
+Make sure to follow the [Storybook's own migration guide](https://storybook.js.org/docs/8/migration-guide).
 We recommend to read it carefully, even though big part of it is not directly related to `@web/storybook-builder` or `@web/storybook-framework-web-components`, many small details are too easy to miss, so go through it step by step.
 
 ## Specific migration notes

diff --git a/docs/docs/storybook-builder/migration-to-storybook-9.md b/docs/docs/storybook-builder/migration-to-storybook-9.md
@@ -0,0 +1,25 @@
+# Storybook Builder >> Migration from Storybook 8 to 9 ||5
+
+## Update dependencies
+
+`@web/storybook-builder` for Storybook 9 is released as version `0.3.x` and expects all Storybook packages to be at least `9.1.20`.
+
+You need to:
+
+- update `@web/storybook-builder` and `@web/storybook-framework-web-components` to `^0.3.0`
+- update dependencies under the namespace `@storybook/*` and the `storybook` itself to `^9.1.20`
+
+## General migration guide
+
+Make sure to follow the [Storybook's own migration guide](https://storybook.js.org/docs/releases/migration-guide-from-older-version).
+We recommend to read it carefully, even though big part of it is not directly related to `@web/storybook-builder` or `@web/storybook-framework-web-components`, many small details are too easy to miss, so go through it step by step.
+
+## Specific migration notes
+
+Apart from Storybook's own migration steps, from the Builder API perspective the `@web/storybook-builder` is considered backwards compatible.
+If you use standard Storybook addons and do not use custom WDS/rollup plugins, you shouldn't require any extra changes.
+
+However, if you do use something custom, here is a list of some changes that might cause highly unlikely difficulties:
+
+- Storybook 9 consolidated most packages it uses into the main storybook packages. These migrated packages and instructions are found in the [migration guide](https://storybook.js.org/docs/releases/migration-guide-from-older-version#package-structure-changes).
+- CSF 3 is now the default format for stories, but CSF 2 is still supported, so if you have CSF 2 stories, they should work without any changes, but we recommend to migrate them to CSF 3 to get all the benefits of it, e.g. better support for TypeScript and better DX in general.
diff --git a/docs/docs/storybook-builder/overview.md b/docs/docs/storybook-builder/overview.md
@@ -31,6 +31,11 @@ Then proceed to the [Configuration](./configuration.md).
 
 ## Storybook versions
 
+Storybook 9 is supported by:
+
+- `@web/storybook-builder@0.3.x`
+- `@web/storybook-framework-web-components@0.3.x`
+
 Storybook 8 is supported by:
 
 - `@web/storybook-builder@0.2.x`