Storybook 8.0 的附加组件迁移指南

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

随着我们收集来自社区的反馈，我们将更新此页面。如果您正在寻找 Storybook 迁移指南，我们还有一个通用的 Storybook 迁移指南.

更新依赖项

首先，更新您的 Storybook 依赖项。使用 next 标签获取预发布版本，使用 latest 获取最新的稳定版本，或者直接指定版本号。

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

附加组件的关键变化

以下是 8.0 版本中影响附加组件开发的重要更改。请查看完整的迁移说明，以获取 8.0 中所有更改的详尽列表。

Node.js 16 支持已停止

请将您的附加组件升级到 Node.js 18，因为 Node.js 16 的支持已结束。

管理器 UI 的 React 18

基于 UI 的附加组件（例如，面板、工具栏、选项卡）依赖 React 18 在 Storybook UI 中渲染其元素。另外，请注意 key 属性不再传递给渲染函数。

不再需要 React 的对等依赖项

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

将 react、react-dom 和全局化的 Storybook 包从 peerDependencies 移动到 devDependencies
将全局化包的列表添加到 tsup 配置中的 externals 属性，以确保它们不是捆绑包的一部分。

例如，请查看我们对 Addon Kit 所做的更新。这些更改是可选的，但建议您进行更改。

这假设您的附加组件使用 tsup 进行捆绑。如果您的附加组件是使用旧版本的 Addon Kit（使用 Babel 进行捆绑）构建的，您必须先切换到 tsup。有关指导，请查看在 Addon Kit 存储库中实施的这些较旧的更改。

@storybook/components 已弃用

来自 @storybook/components 的 Icons 组件现已弃用，建议使用 @storybook/icons。此外，各种 Button 组件属性也已弃用，并提供了替代方法。

Storybook 布局状态 API 更改

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

已弃用功能的移除

7.0 版本中已弃用的包和 API 在 8.0 版本中已被移除。请参阅完整的迁移说明获取详细信息。最值得注意的是，对于附加组件，移除 @storybook/addons 包要求你切换到 @storybook/preview-api 和 @storybook/manager-api 来实现相同的功能。

从 Webpack 中移除 Babel 加载器

Storybook 8 从 Webpack 5 构建器中移除 Babel 加载器。如果你的附加组件的预设覆盖了 babel() 方法，那么如果你的用户使用 SWC 来编译他们的文件（这是基于 Webpack 5 的 Storybook 项目的新默认设置），它将无法正常工作。

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

作为一种解决方法，更新你的文档，告诉用户选择加入 Babel 支持。这将以性能为代价修复你附加组件在他们项目中的问题。

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

Addon Kit 仓库已经更新到支持 Storybook 8.0，你可以将其用作迁移的参考。你将看到本指南中提到的更改，包括通过 type: module 配置的 ESM 支持。作为附加组件维护者，我们鼓励你更新你的附加组件以包含这些更改。它简化了设置，并使用户更容易使用最新版本的 Storybook 来使用你的附加组件。如果你选择继续进行 ESM 迁移，我们已经准备了一个简短的更改列表如下。

package.json 用于依赖项管理、ESM 支持和附加组件入口点的更新。
tsup.config.ts 用于捆绑更改，并考虑 Storybook 的全局变量。
.storybook/local-preset.js 用于支持 ESM 迁移。

要全面了解对 Addon Kit 应用的更改以完全支持 Storybook 8.0，请参阅以下 diff 视图。

发布

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

支持

如果你在按照本指南操作后仍然遇到附加组件的问题，请在我们的 GitHub 仓库中发起新的讨论。