Merge pull request #2870 from modernweb-dev/feat/storybook-8-builder

feat: migrate builder to Storybook 8

Author: bashmish

.changeset/beige-pugs-end.md

@@ -0,0 +1,6 @@
+---
+'@web/storybook-utils': minor
+'@web/mocks': minor
+---
+
+add backwards compatible support for Storybook 8

.changeset/twelve-bears-call.md

@@ -0,0 +1,6 @@
+---
+'@web/storybook-framework-web-components': minor
+'@web/storybook-builder': minor
+---
+
+migrate to Storybook 8

docs/docs/storybook-builder/frameworks.md

@@ -1,6 +1,6 @@
 # Storybook Builder >> Frameworks ||3
 
-Storybook supports different technologies via [frameworks](https://storybook.js.org/docs/web-components/api/new-frameworks).
+Storybook supports different technologies via [frameworks](https://storybook.js.org/docs/api/new-frameworks).
 Frameworks simplify the configuration of the Storybook for a specific builder like `@web/storybook-builder`.
 
 Currently we support only Web Components.

docs/docs/storybook-builder/migration-to-storybook-7.md

@@ -1,8 +1,8 @@
-# Storybook Builder >> Migration to Storybook 7 ||4
+# Storybook Builder >> Migration to Storybook 7 ||5
 
 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`.
 
-Most of the [official migration guide for Storybook 7](https://storybook.js.org/docs/web-components/migration-guide) applies to this migration too, with a few additions and exceptions.
+Most of the [official migration guide for Storybook 7](https://storybook.js.org/docs/7/migration-guide) applies to this migration too, with a few additions and exceptions.
 Please check the official guide, but before running the `upgrade` command read the sections below.
 
 ## Prepare to run upgrade CLI
@@ -70,7 +70,7 @@ If you use `rollupConfig`, rename it to `rollupFinal`.
 
 `@web/dev-server-storybook` was a plugin of `@web/dev-server`, therefore you used to run Storybook via [`@web/dev-server` CLI](../dev-server/cli-and-configuration.md).
 
-With the introduction of [builders](https://storybook.js.org/docs/web-components/builders/overview) in Storybook 7 this is no longer the case and you can make use of [Storybook CLI](https://storybook.js.org/docs/web-components/api/cli-options).
+With the introduction of [builders](https://storybook.js.org/docs/7/builders) in Storybook 7 this is no longer the case and you can make use of [Storybook CLI](https://storybook.js.org/docs/7/api/cli-options).
 
 Typically you'll use `storybook dev` and `storybook build` to start the dev server and create a static build for deployment.
 

docs/docs/storybook-builder/migration-to-storybook-8.md

@@ -0,0 +1,25 @@
+# Storybook Builder >> Migration from Storybook 7 to 8 ||4
+
+## Update dependencies
+
+`@web/storybook-builder` for Storybook 8 is released as version `0.2.x` and expects all Storybook packages to be at least `8.5.0`.
+
+You need to:
+
+- update `@web/storybook-builder` and `@web/storybook-framework-web-components` to `^0.2.0`
+- update dependencies under the namespace `@storybook/*` and the `storybook` itself to `^8.5.0`
+
+## General migration guide
+
+Make sure to follow the [Storybook's own migration guide](https://storybook.js.org/docs/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
+
+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:
+
+- the Storybook dependencies graph was optimized, some packages are now consolidated and 3rd-party dependencies are bundled into Storybook packages, which brings a lot of improvements, e.g. simplifies managing and updating the Storybook 8 between minor versions and decreases the runtime bundling required on the builder side, but this also means that some dependencies might behave differently since they are now bundled by Storybook itself, on top of it we came across the code that's not browser compatible (e.g. the usage of `process`) and now needs to be transpiled on-the-fly
+- MDX was upgraded from 2 to 3 following the Storybook's requirement, the integration of it in the builder needed to be updated too due to a changes in the Storybook packages and some removed APIs

docs/docs/storybook-builder/overview.md

@@ -8,7 +8,7 @@ eleventyNavigation:
 
 # Web Storybook Builder
 
-`@web/storybook-builder` is a [Storybook builder](https://storybook.js.org/docs/web-components/builders/overview) powered by [`@web/dev-server`](../dev-server/overview.md).
+`@web/storybook-builder` is a [Storybook builder](https://storybook.js.org/docs/builders) powered by [`@web/dev-server`](../dev-server/overview.md).
 If you are using the ecosystem of `@web/dev-server` and `@web/test-runner`, then this is the right choice for your Storybook setup.
 
 ## Installation
@@ -29,6 +29,18 @@ npm install @web/storybook-framework-web-components --save-dev
 
 Then proceed to the [Configuration](./configuration.md).
 
-## Migration
+## Storybook versions
+
+Storybook 8 is supported by:
+
+- `@web/[email protected]`
+- `@web/[email protected]`
+
+Storybook 7 is supported by:
+
+- `@web/[email protected]`
+- `@web/[email protected]`
+
+## Migration from @web/dev-server-storybook
 
 If you are migrating from the `@web/dev-server-storybook` plugin to Storybook 7, please read the [Migration to Storybook 7 guide](./migration-to-storybook-7.md).