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 属性不再传递给渲染函数。

¥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，你可以使用 卸载插件 构建一个自定义打包插件，该插件可与 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 支持。作为插件维护者，我们鼓励你更新插件以包含 Babel 支持。它简化了设置，使用户能够更轻松地将你的插件与最新版本的 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.