mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-04 11:01:07 +08:00
154 lines
5.0 KiB
Plaintext
154 lines
5.0 KiB
Plaintext
---
|
||
title: Storybook for Web components & Webpack
|
||
sidebar:
|
||
order: 13
|
||
title: Web components & Webpack
|
||
---
|
||
|
||
Storybook for Web components & Webpack is a [framework](../../contribute/framework.mdx) that makes it easy to develop and test UI components in isolation for applications using [Web components](https://www.webcomponents.org/introduction) built with [Webpack](https://webpack.js.org/).
|
||
|
||
<If notRenderer="web-components">
|
||
<Callout variant="info">
|
||
Storybook for Web components & Webpack is only supported in [Web components](?renderer=web-components) projects.
|
||
</Callout>
|
||
|
||
{/* End non-supported renderers */}
|
||
</If>
|
||
|
||
<If renderer="web-components">
|
||
## Requirements
|
||
|
||
* Webpack ≥ 5.0
|
||
* Storybook ≥ 8.0
|
||
|
||
## Getting started
|
||
|
||
### In a project without Storybook
|
||
|
||
Follow the prompts after running this command in your Web components project's root directory:
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="create-command.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
[More on getting started with Storybook.](../install.mdx)
|
||
|
||
### In a project with Storybook
|
||
|
||
This framework is designed to work with Storybook 7+. If you’re not already using v7, upgrade with this command:
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="storybook-upgrade.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
#### Automatic migration
|
||
|
||
When running the `upgrade` command above, you should get a prompt asking you to migrate to `@storybook/web-components-webpack5`, which should handle everything for you. In case that auto-migration does not work for your project, refer to the manual migration below.
|
||
|
||
#### Manual migration
|
||
|
||
First, install the framework:
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="web-components-webpack5-install.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
Next, install and register your appropriate compiler addon, depending on whether you're using SWC (recommended) or Babel:
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="storybook-addon-compiler-swc-auto-install.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
or
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="storybook-addon-compiler-babel-auto-install.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
More details can be found in the [Webpack builder docs](../../builders/webpack.mdx#compiler-support).
|
||
|
||
Finally, update your `.storybook/main.js|ts` to change the framework property:
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="web-components-webpack5-add-framework.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
## Hot Module Reloading (HMR)
|
||
|
||
Web components are registered on a global registry, which only accepts a given name/class once. That can lead to errors when using classical HMR. While there are ideas for achieving HMR with a static registry, there has yet to be a proven solution. Therefore, the best approach, for now, is to do full-page reloads while developing. You can ensure that page reloads happen quickly by defining your stories as specific states of components (which we recommend regardless).
|
||
|
||
## Set up ES6/7 dependencies
|
||
|
||
By default, Storybook only works with precompiled ES5 code. Because most Web Components and their libs are distributed as ES2017, you must mark those packages as "needs transpilation" manually.
|
||
|
||
For example, if you have a library called `my-library` which is in ES2017, then you can configure your project like so:
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="web-components-webpack5-transpilation.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
By default, the following folders are transpiled:
|
||
|
||
* `src/*.js`
|
||
* `packages/*/src/*.js`
|
||
* `node_modules/lit-html/*.js`
|
||
* `node_modules/lit-element/*.js`
|
||
* `node_modules/@open-wc/*.js`
|
||
* `node_modules/@polymer/*.js`
|
||
* `node_modules/@vaadin/*.js`
|
||
|
||
<Callout variant="info">
|
||
Note that the `src` folder is also included. This provides extra configuration for `import.meta` and other features.
|
||
|
||
If you use a folder for your components/stories other than `src`, you must use the configuration example above to have it correctly transpiled.
|
||
</Callout>
|
||
|
||
## API
|
||
|
||
### Options
|
||
|
||
You can pass an options object for additional configuration if needed:
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="web-components-webpack5-framework-options.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
The available options are:
|
||
|
||
#### `builder`
|
||
|
||
Type: `Record<string, any>`
|
||
|
||
Configure options for the [framework's builder](../../api/main-config/main-config-framework.mdx#optionsbuilder). For this framework, available options can be found in the [Webpack builder docs](../../builders/webpack.mdx).
|
||
|
||
## Troubleshooting
|
||
|
||
### Error while developing with HMR
|
||
|
||
While developing a component, you might encounter this error:
|
||
|
||
```sh
|
||
Failed to execute 'define' on 'CustomElementRegistry': the name "..." has already been used with this registry
|
||
```
|
||
|
||
This error occurs because the component is already registered in the global registry. For more information, see the [limitations of HMR with web components](#hot-module-reloading-hmr).
|
||
|
||
{/* End supported renderers */}
|
||
</If>
|