Storybook 8.0 的插件迁移指南

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

当我们收集社区的反馈时，我们将更新此页面。如果您正在寻找通用 Storybook 迁移指南，我们也有提供。

更新依赖项

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

package.json

{
  "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 prop 不再传递给渲染函数。

不再需要 React 对等依赖

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

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

有关示例，请参阅我们对 Addon Kit 所做的更新。这些更改是可选的，但建议使用。

这假定您的插件使用 tsup 进行捆绑。如果您的插件是使用旧版本的 Addon Kit 构建的，该工具包使用 Babel 进行捆绑，则必须首先切换到 tsup。有关指南，请浏览 Addon Kit 存储库中实现的这些较旧的更改。

@storybook/components 弃用

来自 @storybook/components 的 Icons 组件现已弃用，推荐使用 @storybook/icons。此外，Button 组件的各种 props 也已弃用，并提供了替代方案。

Storybook 布局状态 API 更改

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

移除已弃用的功能

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

从 Webpack 中移除 Babel-loader

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

为了确保您的插件同时支持 Babel 和 SWC，您可以使用 Unplugin 构建自定义捆绑插件，该插件将与 Webpack 和 Vite 构建器一起工作，让您可以完全控制在加载 stories 和组件时运行 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 的更改的完整概述，请参阅以下差异视图。

发布

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

支持

如果您在遵循本指南后仍然遇到插件问题，请在我们的 GitHub 存储库中打开新的讨论。