Storybook 8.0 插件迁移指南

我们真诚感谢插件创建者为保持 Storybook 生态系统的活力和最新性所付出的奉献和努力。随着 Storybook 发展到 8.0 版，带来新功能和改进，本指南旨在帮助你将插件从 7.x 迁移到 8.0。如果你需要从早期版本的 Storybook 迁移插件，请首先参考 Storybook 7.0 插件迁移指南。

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

更新依赖

¥Updating dependencies

首先更新你的 Storybook 依赖。使用 next 标签表示预发布版本，latest 表示最新稳定版本，或者直接指定版本。

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

{
  "dependencies": {
    "@storybook/client-logger": "next" // or "latest", or "^8.0.0"
  }
}

插件的主要变化

¥Key changes for addons

以下是版本 8.0 中影响插件开发的重要更改。请查看 完成迁移说明 以获取 8.0 中的完整更改列表。

¥Here are the essential changes in version 8.0 that impact addon development. Please check the complete migration note for an exhaustive list of changes in 8.0.

Node.js 16 支持已放弃

¥Node.js 16 support dropped

请将你的插件升级到 Node.js 18，因为对 Node.js 16 的支持已经结束。

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

用于管理器 UI 的 React 18

¥React 18 for manager UI

基于 UI 的插件（例如 panels、toolbars、tabs）依赖 React 18 在 Storybook UI 中渲染其元素。另外，请注意 key prop 不再传递给渲染函数。

¥UI-based addons (e.g., panels, toolbars, 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 对等依赖

¥React peer dependency is no longer required

要删除插件对 React 的对等依赖并减少其安装大小，请执行以下操作：

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

1. 将 react、react-dom 和全球化 Storybook 包从 peerDependencies 移动到 devDependencies

   ¥Move react, react-dom, and the globalized Storybook packages from peerDependencies to devDependencies

2. 将全球化包列表添加到 tsup 配置中的 externals 属性，以确保它们不是打包包的一部分。

   ¥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. These changes are optional but recommended.

@storybook/components deprecations

@storybook/components 中的 Icons 组件现已弃用，取而代之的是 @storybook/icons。此外，各种 Button 组件属性也已弃用，并提供替代方案。

¥The Icons component from @storybook/components is now deprecated in favor of @storybook/icons. Additionally, various Button component props are also deprecated, with alternatives provided.

Storybook 布局状态 API 更改

¥Storybook layout state API changes

如果你使用 addons.setConfig({...}) 自定义 Storybook UI 配置，请注意 布局状态 API 的更改。

¥If you're customizing the Storybook UI configuration with addons.setConfig({...}), be aware of the changes to the layout state API.

删除已弃用的功能

¥Removal of deprecated features

7.0 中已弃用的包和 API 现在已在 8.0 中删除。有关详细信息，请参阅 完整迁移说明。最值得注意的是，对于插件，删除 @storybook/addons 包需要你切换到 @storybook/preview-api 和 @storybook/manager-api 才能获得相同的功能。

¥Deprecated packages and APIs from 7.0 are now removed in 8.0. Consult the full migration notes 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.

从 Webpack 中删除 Babel-loader

¥Babel-loader removed from Webpack

Storybook 8 从 webpack5 构建器中删除 babel-loader。如果你的插件的预设覆盖了 babel() 方法，则如果你的用户使用 SWC 编译他们的文件（这是基于 Webpack 5 的 Storybook 项目的新默认设置），它将中断。

¥Storybook 8 removes babel-loader from the webpack5 builder. 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).

为了确保你的插件同时支持 Babel 和 SWC，你可以使用 Unplugin 构建一个自定义打包插件，该插件可与 Webpack 和 Vite 构建器一起使用，让你完全控制在故事和组件加载时运行 Babel（或任何你想要的）。

¥To ensure your addon supports both Babel and SWC, you can build a custom bundling plugin using Unplugin 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.

作为一种解决方法，请更新你的文档以告知用户选择加入 Babel 支持。这应该会以牺牲性能为代价修复他们项目中的插件：

¥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:

npx storybook@latest add @storybook/addon-webpack5-compiler-babel

迁移示例

¥Migration Example

Addon Kit repository 已更新以支持 Storybook 8.0，你可以将其用作迁移的参考。你将看到本指南中提到的更改，包括通过 type: module 配置实现的 ESM 支持。作为插件维护者，我们鼓励你更新你的插件以包含它们。它简化了设置，使用户更容易将你的插件与最新版本的 Storybook 一起使用。如果你选择跟随 ESM 迁移，我们在下面准备了一个简短的更改列表。

¥The Addon Kit repository 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 用于依赖管理、ESM 支持和对插件入口点的更新。

  ¥package.json for dependency management, ESM support and updates to the addon's entry points.

• tsup.config.ts 用于打包更改，考虑到 Storybook 的全局变量。

  ¥tsup.config.ts for bundling changes, factoring in Storybook's globals.

• .storybook/local-preset.js 用于支持 ESM 迁移。

  ¥.storybook/local-preset.js to support the ESM migration.

发布

¥Releasing

为了支持 Storybook 8.0，我们鼓励你发布插件的新主要版本，并继续使用次要版本或补丁版本支持 7.x。对于实验性功能或测试，请选择 next 标签。这将允许你在项目中测试你的插件并在发布稳定版本之前收集反馈。

¥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

如果你按照本指南操作后仍然遇到插件问题，请在我们的 GitHub 存储库中打开 新讨论。

¥If you're still having issues with your addon after following this guide, please open a new discussion in our GitHub repository.