feat: storybook-builder and storybook-framework-web-components

docs/docs/storybook-builder/configuration.md

@@ -0,0 +1,132 @@
+# Storybook Builder >> Configuration ||2
+
+`@web/storybook-builder` aims at compatibility with standard Storybook features, e.g. configuration of preview (`.storybook/preview.js`), official addons, etc.
+You can follow the [official Storybook docs](https://storybook.js.org/) for the general setup and configuration options.
+
+> This documentation is written with Web Components and `@web/storybook-framework-web-components` in mind.
+> Information about supported frameworks can be found [here](./frameworks.md).
+
+You can use the `storybook init` CLI command with interactive setup.
+Choose Web Components and any builder when asked by the CLI.
+
+When you finish the setup you'll have a standard Storybook folder with configuration files (`.storybook` by default) containing at least `main.js`.
+
+## Configuring builder and framework
+
+Set the `type` and `framework` in `main.js`:
+
+- set the `config` type to `import('@web/storybook-framework-web-components').StorybookConfig`
+- set the `framework.name` to `'@web/storybook-framework-web-components'`
+
+```js
+// .storybook/main.js
+
+/** @type { import('@web/storybook-framework-web-components').StorybookConfig } */
+const config = {
+  ...
+  framework: {
+    name: '@web/storybook-framework-web-components',
+  },
+  ...
+};
+
+export default config;
+```
+
+## Configuring dev server
+
+The builder implements a backend for the `storybook dev` CLI command and comes with a default `@web/dev-server` configuration which adheres to browser standards and supports official addons of the Storybook ecosystem.
+
+### `@web/dev-server` configuration file
+
+When Storybook is loaded, the builder's default `@web/dev-server` config gets automatically merged with the project's [configuration file (`web-dev-server.config.{mjs,cjs,js}`)](../dev-server/cli-and-configuration.md#configuration-file) if present.
+This is needed to ensure that the same configuration is used for application, feature or design system you are building.
+
+### Option `framework.options.builder.wdsConfigPath`
+
+You can configure a different path to the configuration file using `framework.options.builder.wdsConfigPath`, relative to CWD:
+
+```js
+// .storybook/main.js
+
+/** @type { import('@web/storybook-framework-web-components').StorybookConfig } */
+const config = {
+  ...
+  framework: {
+    name: '@web/storybook-framework-web-components',
+    options: {
+      builder: {
+        wdsConfigPath: 'storybook-wds.config.mjs',
+      },
+    },
+  },
+  ...
+};
+
+export default config;
+```
+
+### Option `wdsFinal`
+
+Sometimes you might need to add Storybook specific configuration for the dev server, you can use the `wdsFinal` option for this:
+
+```js
+// .storybook/main.js
+
+/** @type { import('@web/storybook-framework-web-components').StorybookConfig } */
+const config = {
+  ...
+  framework: {
+    name: '@web/storybook-framework-web-components',
+  },
+  async wdsFinal(config) {
+    // add Storybook specific configuration for `@web/dev-server`
+    // e.g. "open" to go to a custom URL in the browser when server has started
+    config.open = '/custom-path';
+    return config;
+  },
+  ...
+};
+
+export default config;
+```
+
+The `config` parameter is a `@web/dev-server` config, you can use this to customize your `@web/dev-server` options and plugins.
+
+> When using rollup plugins make sure to [convert them to `@web/dev-server` ones](../dev-server/plugins/rollup.md).
+
+## Configuring static build
+
+The builder implements a backend for the `storybook build` CLI command and comes with a default `rollup` configuration which adheres to browser standards and supports official addons of the Storybook ecosystem.
+
+### Option `rollupFinal`
+
+Sometimes you might need to add some extra configuration for the static build, you can use the `rollupFinal` option for this:
+
+```js
+// .storybook/main.js
+import polyfillsLoader from '@web/rollup-plugin-polyfills-loader';
+
+/** @type { import('@web/storybook-framework-web-components').StorybookConfig } */
+const config = {
+  ...
+  framework: {
+    name: '@web/storybook-framework-web-components',
+  },
+  async rollupFinal(config) {
+    // add extra configuration for rollup
+    // e.g. a new plugin
+    config.plugins.push(polyfillsLoader({
+      polyfills: {
+        esModuleShims: true,
+      },
+    }));
+    return config;
+  },
+  ...
+};
+
+export default config;
+```
+
+The `config` parameter is a `rollup` config, you can use this to customize your `rollup` options and plugins.

docs/docs/storybook-builder/frameworks.md

@@ -0,0 +1,36 @@
+# Storybook Builder >> Frameworks ||3
+
+Storybook supports different technologies via [frameworks](https://storybook.js.org/docs/web-components/api/new-frameworks).
+Frameworks simplify the configuration of the Storybook for a specific builder like `@web/storybook-builder`.
+
+Currently we support only Web Components.
+
+## @web/storybook-framework-web-components
+
+Storybook framework for `@web/storybook-builder` + Web Components
+
+### Installation
+
+Install the framework:
+
+```bash
+npm install @web/storybook-framework-web-components --save-dev
+```
+
+### Configuration
+
+Configure the type and framework name in the Storybook main configuration file:
+
+```js
+// .storybook/main.js
+
+/** @type { import('@web/storybook-framework-web-components').StorybookConfig } */
+const config = {
+  ...
+  framework: {
+    name: '@web/storybook-framework-web-components',
+    ...
+  },
+  ...
+};
+```

docs/docs/storybook-builder/index.md

@@ -0,0 +1 @@
+# Storybook Builder ||4

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

@@ -0,0 +1,117 @@
+# Storybook Builder >> Migration to Storybook 7 ||4
+
+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.
+Please check the official guide, but before running the `upgrade` command read the sections below.
+
+## Prepare to run upgrade CLI
+
+The Storybook CLI `upgrade` command is not aware of the `@web/dev-server-storybook` plugin and as a result it won't work by default.
+But with a simple workaround you can make it work.
+
+First, install the old version of `builder-vite` and old Storybook 6 renderer for the technology you used in the old setup, e.g. for Web Components it will be:
+
+```bash
+npm install @storybook/builder-vite@0.4 @storybook/web-components@6 --save-dev
+```
+
+Then proceed with the `upgrade` script and follow it's interactive process:
+
+```bash
+npx storybook@latest upgrade
+```
+
+Then [configure the builder and framework](./configuration.md#configuring-builder-and-framework) in the main Storybook configuration.
+
+## Uninstall old packages
+
+```bash
+npm uninstall @web/dev-server-storybook @web/storybook-prebuilt --save-dev
+```
+
+## Install addons
+
+The old Storybook 6 bundle `@web/storybook-prebuilt` came with a few preconfigured addons.
+In the new setup you'll need to install and configure them explicitly.
+
+We recommend to install the following addons:
+
+```bash
+npm install @storybook/addon-essentials @storybook/addon-links --save-dev
+```
+
+Then register them in the Storybook main configuration file:
+
+```js
+// .storybook/main.js
+
+/** @type { import('@web/storybook-framework-web-components').StorybookConfig } */
+const config = {
+  ...
+  addons: [
+    '@storybook/addon-essentials',
+    '@storybook/addon-links',
+    ...
+  ],
+  ...
+};
+
+export default config;
+```
+
+## Rename rollupConfig to rollupFinal
+
+For consistency with other similar hooks in the Storybook ecosystem, including `@web/storybook-builder`'s `wdsFinal`, the rollup hook was renamed to `rollupFinal`.
+
+If you use `rollupConfig`, rename it to `rollupFinal`.
+
+## Change CLI commands
+
+`@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).
+
+Typically you'll use `storybook dev` and `storybook build` to start the dev server and create a static build for deployment.
+
+So you need to update your NPM scripts accordingly:
+
+```js
+// package.json
+{
+  "scripts": {
+    "storybook:start": "storybook dev -p 6006",
+    "storybook:build": "storybook build --output-dir demo-storybook",
+  },
+}
+```
+
+## Usage of ESM
+
+Storybook 7 supports ES modules for configuration files, so we recommend using standard ESM syntax for imports and exports in `.storybook/main.js` and other configuration files.
+
+## Storybook specific configuration
+
+The usage of `web-dev-server.config.{mjs,cjs,js}` file for Storybook specific configuration is not recommended.
+You should use this file for your project dev server.
+
+If you have a Storybook specific configuration, move it to the [wdsFinal hook](./configuration.md#option-wdsfinal) instead.
+
+### Option "port"
+
+The `port` configured in `web-dev-server.config.{mjs,cjs,js}` won't have any effect on the Storybook, because Storybook CLI runs it's own dev server.
+
+To open Storybook dev server on a certain port use the Storybook CLI argument instead:
+
+```bash
+storybook dev -p XXXX
+```
+
+### Option "open"
+
+The `open` URL configured in `web-dev-server.config.{mjs,cjs,js}` won't have any effect on the Storybook, because it conflicts with the Storybook auto-open behavior.
+
+To open a non-default URL do the following:
+
+- disable open in Storybook CLI, e.g. `storybook dev -p XXXX --no-open`
+- configure `open` in [wdsFinal hook](./configuration.md#option-wdsfinal)

docs/docs/storybook-builder/overview.md

@@ -0,0 +1,34 @@
+---
+eleventyNavigation:
+  key: Storybook Builder >> Overview
+  title: Overview
+  parent: Storybook Builder
+  order: 1
+---
+
+# 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).
+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
+
+Install the `@web/storybook-builder`:
+
+```bash
+npm install @web/storybook-builder --save-dev
+```
+
+Install a framework, e.g. for Web Components:
+
+> Information about supported frameworks can be found [here](./frameworks.md).
+
+```bash
+npm install @web/storybook-framework-web-components --save-dev
+```
+
+Then proceed to the [Configuration](./configuration.md).
+
+## Migration
+
+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).