Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Polish Addon migration guide #26175

Merged
merged 2 commits into from
Feb 23, 2024
Merged

Docs: Polish Addon migration guide #26175

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9a98e0b
Docs: Polish Addon migration guide
jonniebigodes Feb 23, 2024
b70a428
Merge branch 'next' into docs_adjust_addon_migration_guide
jonniebigodes Feb 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 27 additions & 19 deletions docs/addons/addon-migration-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Addon migration guide for Storybook 8.0
---

We deeply appreciate the dedication and effort addon creators put into keeping the Storybook ecosystem vibrant and up-to-date. As Storybook evolves to version 8.0, bringing new features and improvements, this guide is here to assist you in migrating your addons from 7.x to 8.0. If you need to migrate your addon from an earlier version of Storybook, please first refer to the [Addon migration guide for Storybook 7.0](https://storybook.js.org/docs/7.6/addons/addon-migration-guide).
We sincerely appreciate the dedication and effort addon creators put into keeping the Storybook ecosystem vibrant and up-to-date. As Storybook evolves to version 8.0, bringing new features and improvements, this guide is here to assist you in migrating your addons from 7.x to 8.0. If you need to migrate your addon from an earlier version of Storybook, please first refer to the [Addon migration guide for Storybook 7.0](https://storybook.js.org/docs/7.6/addons/addon-migration-guide).

<Callout variant="info">

Expand All @@ -14,7 +14,7 @@ As we gather feedback from the community, we’ll update this page. We also have

Begin by updating your Storybook dependencies. Use the `next` tag for pre-release versions, `latest` for the most recent stable release, or specify the version directly.

```json
```jsonc
{
"dependencies": {
"@storybook/client-logger": "next" // or "latest", or "^8.0.0"
Expand All @@ -24,54 +24,62 @@ Begin by updating your Storybook dependencies. Use the `next` tag for pre-releas

## Key changes for addons

Here are the essential changes in version 8.0 that impact addon development. Please check the [full migration note](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-7x-to-800) for an exhaustive list of changes in 8.0.
Here are the essential changes in version 8.0 that impact addon development. Please check the [complete migration note](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-7x-to-800) for an exhaustive list of changes in 8.0.

### Node.js 16 support dropped

Please upgrade your addon to Node.js 18, as support for Node.js 16 has ended.

### React 18 for manager UI

UI injected into panels, tools, etc. by addons is now rendered with React 18. Also note that the `key` prop is no longer passed to the render function.
UI-based addons (e.g., [panels](../addons/addon-types.md#panels), [toolbars](../addons/addon-types.md#toolbars), [tabs](../addons/addon-types.md#tabs)) rely on React 18 to render their elements in the Storybook UI. Also, note that the `key` prop is no longer passed to the render function.

### React peer dependency is no longer required

To remove your addon's peer dependency on React, and reduce its install size, do the following:
To remove your addon's peer dependency on React and reduce its install size, do the following:

1. Move `react`, `react-dom` and the globalized Storybook packages from `peerDependencies` to `devDependencies`
2. Add the list of globalized packages to the `externals` property in the `tsup` configuration, to ensure they are not part of the bundle.
1. Move `react`, `react-dom`, and the globalized Storybook packages from `peerDependencies` to `devDependencies`
2. Add the list of globalized packages to the `externals` property in the `tsup` configuration to ensure they are not part of the bundle.

For an example, see [the updates we've made to the addon-kit](https://github.com/storybookjs/addon-kit/pull/60/files#diff-8fed899bdbc24789a7bb4973574e624ed6207c6ce572338bc3c3e117672b2a20). These changes are optional but recommended.
For an example, see [the updates we've made to the Addon Kit](https://github.com/storybookjs/addon-kit/pull/60/files#diff-8fed899bdbc24789a7bb4973574e624ed6207c6ce572338bc3c3e117672b2a20). These changes are optional but recommended.

<Callout variant="info">
<Callout variant="info">

This assumes your addon is using tsup for bundling. If your addon was built with an older version of addon-kit that uses Babel for bundling, you have to first switch to tsup. For guidance, explore these [older changes implemented in the addon-kit](https://github.com/storybookjs/addon-kit/pull/45/files).
This assumes your addon uses [tsup](https://tsup.egoist.dev/) for bundling. If your addon was built with an older version of the Addon Kit that uses Babel for bundling, you must first switch to tsup. For guidance, explore these older changes implemented in the Addon Kit [repository](https://github.com/storybookjs/addon-kit/pull/45/files).

</Callout>

### @storybook/components deprecations

`Icons` component from `@storybook/components` is now deprecated in favor of [`@storybook/icons`](https://github.com/storybookjs/icons). Additionally, various `Button` component props are also deprecated, with alternatives provided.
The `Icons` component from `@storybook/components` is now deprecated in favor of [`@storybook/icons`](https://github.com/storybookjs/icons). Additionally, various `Button` component props are also deprecated, with alternatives provided.

### Storybook layout state API changes

If you're customizing the Storybook UI configuration with `addons.setConfig({...})`, be aware of [the changes to the layout state API](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#ui-layout-state-has-changed-shape).

### Removal of deprecated features

Deprecated packages and APIs from 7.0 are now removed in 8.0.Consult the [full migration notes](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#deprecations-which-are-now-removed) for details. Most notably for addons, the removal of the `@storybook/addons` now necessitates a switch to `@storybook/preview-api` and `@storybook/manager-api`.
Deprecated packages and APIs from 7.0 are now removed in 8.0. Consult the [full migration notes](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#deprecations-which-are-now-removed) for details. Most notably, for addons, the removal of the `@storybook/addons` package requires you to switch to `@storybook/preview-api` and `@storybook/manager-api` for the same functionality.

### Babel-loader removed from webpack
### Babel-loader removed from Webpack

Storybook 8 [removes babel-loader from the webpack5 builder](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#removed-babelcore-and-babel-loader-from-storybookbuilder-webpack5). If your addon's preset overrides the `babel()` method, it will break if your users are using SWC to compile their files (which is the new default for Webpack 5-based Storybook projects).

To solve for both Babel and SWC, the most robust approach is to create an [unplugin](https://github.com/unjs/unplugin) that will work with both Webpack and Vite builders. That will give you full control to run Babel (or whatever you want) on stories and components as they are loaded.
To ensure your addon supports both Babel and SWC, you can build a custom bundling plugin using [Unplugin](https://unplugin.vercel.app/) that will work with both Webpack and Vite builders, giving you complete control to run Babel (or whatever you want) on stories and components as they are loaded.

As a workaround, update your documentation to tell users to opt-in to Babel support. This should fix your addon in their project, at the cost of performance:
As a workaround, update your documentation to tell users to opt-in to Babel support. This should fix your addon in their project at the cost of performance:

```sh
npx storybook@latest add @storybook/addon-webpack5-compiler-babel
```
<!-- prettier-ignore-start -->

<CodeSnippets
paths={[
'common/storybook-addon-compiler-babel-auto-install.npm.js.mdx',
'common/storybook-addon-compiler-babel-auto-install.pnpm.js.mdx',
'common/storybook-addon-compiler-babel-auto-install.yarn.js.mdx',
]}
/>

<!-- prettier-ignore-end -->

## Migration Example

Expand All @@ -89,7 +97,7 @@ If you migrate your addon to support ESM, you can safely remove any `manager.js`

## Releasing

Release a new major version of your addon for Storybook 8.0. We recommend you to continue supporting 7.x with minor or patch versions. We also recommend releasing your own addon using the `next` tag to test it out in projects.
To support Storybook 8.0, we encourage you to release a new major version of your addon and continue supporting 7.x with minor or patch versions. For experimental features or testing, opt for the `next` tag. This will allow you to test your addon in projects and gather feedback before releasing a stable version.

## Support

Expand Down
4 changes: 2 additions & 2 deletions docs/snippets/common/storybook-addon-panel-example.js.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ addons.register('my/panel', () => {
title: 'Example Storybook panel',
//👇 Sets the type of UI element in Storybook
type: types.PANEL,
render: ({ active, key }) => (
<AddonPanel key="panel" active={isActive}>
render: ({ active }) => (
<AddonPanel active={active}>
<h2>I'm a panel addon in Storybook</h2>
</AddonPanel>
),
Expand Down
Loading