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.

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: Add "React peer dependency is no longer required" section to addon migration guide #25826

Merged
merged 9 commits into from
Feb 20, 2024
29 changes: 29 additions & 0 deletions docs/addons/addon-migration-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,21 @@ Please upgrade your addon to Node.js 18, as support for Node.js 16 has ended.

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.

### React peer dependency is no longer required
vanessayuenn marked this conversation as resolved.
Show resolved Hide resolved

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.

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">

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).

</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.
Expand All @@ -58,6 +73,20 @@ As a workaround, update your documentation to tell users to opt-in to Babel supp
npx storybook@latest add @storybook/addon-webpack5-compiler-babel
```

## Migration Example

The Addon Kit [repository](https://github.com/storybookjs/addon-kit) has already been updated to support Storybook 8.0, and you can use it as a reference for your migration. You'll see the changes mentioned in this guide, including ESM support via the `type: module` configuration. As an addon maintainer, we encourage you to update your addon to include them. It simplifies the setup and makes it easier for users to use your addon with the latest version of Storybook. If you choose to follow along with the ESM migration, we've prepared an abbreviated list of changes below.

- [`package.json`](https://github.com/storybookjs/addon-kit/compare/79282986..cf0875f#diff-7ae45ad102eab3b6d7e7896acd08c427a9b25b346470d7bc6507b6481575d519) for dependency management, ESM support and updates to the addon's entry points.
- [`tsup.config.ts`](https://github.com/storybookjs/addon-kit/compare/79282986..cf0875f#diff-8fed899bdbc24789a7bb4973574e624ed6207c6ce572338bc3c3e117672b2a2) for bundling changes, factoring in Storybook's globals.
- [`.storybook/local-preset.js`](https://github.com/storybookjs/addon-kit/compare/79282986..cf0875f#diff-390b53ea479b1ceffcbf31944f644ee23aa9f337b75a8a0ffd815bed50d376cb) to support the ESM migration.

<Callout variant="info" icon="💡">

If you migrate your addon to support ESM, you can safely remove any `manager.js`, `preview.js`, and `preset.js` files from the addon's root directory. For a complete overview of the changes applied to the Addon Kit to fully support Storybook 8.0, see the following [diff view](https://github.com/storybookjs/addon-kit/compare/79282986..cf0875f).

</Callout>

## 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.
Expand Down
Loading