Storybook 9.0 插件迁移指南

我们真诚感谢插件创建者为保持 Storybook 生态系统的活力和最新性所付出的奉献和努力。随着 Storybook 升级到 9.0 版本，带来诸多新功能和改进，本指南旨在帮助你将插件从 8.x 版本迁移到 9.0 版本。如果你需要从早期版本的 Storybook 迁移插件，请首先参考 Storybook 8.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 9.0, bringing new features and improvements, this guide is here to assist you in migrating your addons from 8.x to 9.0. If you need to migrate your addon from an earlier version of Storybook, please first refer to the Addon migration guide for Storybook 8.0.

替换依赖

¥Replacing dependencies

许多先前发布的软件包都包含 已移至 Storybook 核心。如果你的插件依赖于这些包，则应将其从 package.json 中移除，并更新插件以从新位置导入。如果你的插件尚未依赖于 storybook 包，则应将其作为依赖添加到 package.json 中。

¥Many previously-published packages have moved to be part of Storybook's core. If your addon depends on any of these packages, you should remove them from your package.json and update your addon to import from the new location. If your addon does not already depend on the storybook package, you should add it to your package.json as a dependency.

{
  "devDependencies": {
    "storybook": "next" // or "latest", or "^9.0.0"
  }
}

依赖管理

¥Dependency Management

在 Storybook 9.0 中，大多数 Storybook 包已整合到主 storybook 包中。这意味着你不再需要将各个 Storybook 包作为依赖引用。或者，将 storybook 定义为插件 package.json 中的对等依赖：

¥With Storybook 9.0, most Storybook packages have been consolidated into the main storybook package. This means you no longer need to reference individual Storybook packages as dependencies. Instead, define storybook as a peer dependency in your addon's package.json:

{
  "name": "your-storybook-addon",
  "peerDependencies": {
    "storybook": "^9.0.0"
  },
  "devDependencies": {
    "storybook": ">=9.0.0-0 <10.0.0-0" // For local development
  }
}

此方法确保：

¥This approach ensures that:

1. 你的插件使用与宿主项目相同版本的 Storybook API。

   ¥Your addon uses the same version of Storybook APIs as the host project

2. 你可以避免最终打包文件中出现重复的 Storybook 包。

   ¥You avoid duplicate Storybook packages in the final bundle

3. 你的插件包大小已最小化。

   ¥Your addon's package size is minimized

如果你的插件支持 Storybook 的多个主要版本，则可以在同级依赖中指定更广泛的版本范围：

¥If your addon supports multiple major versions of Storybook, you can specify a wider version range in your peer dependencies:

{
  "name": "your-storybook-addon",
  "peerDependencies": {
    "storybook": "^8.0.0 || ^9.0.0"
  },
  "devDependencies": {
    "storybook": ">=9.0.0-0 <10.0.0-0" // For local development
  }
}

但是，我们建议你在发布 Storybook 新主要版本的同时，也发布插件的新主要版本。此实践：

¥However, we recommend releasing a new major version of your addon alongside new major versions of Storybook. This practice:

1. 使代码维护更容易

   ¥Makes it easier to maintain your code

2. 允许你利用新功能和改进

   ¥Allows you to take advantage of new features and improvements

3. 为你的用户提供更清晰的升级路径

   ¥Provides a clearer upgrade path for your users

插件的主要变化

¥Key changes for addons

以下是版本 9.0 中影响插件开发的关键变更。

¥Here are the essential changes in version 9.0 that impact addon development.

包合并

¥Package Consolidation

多个包已合并到主 storybook 包中。更新导入以使用新路径：

¥Several packages have been consolidated into the main storybook package. Update your imports to use the new paths:

此外，一些内部包已移至 /internal 子路径下。这些路径不属于我们的公共 API，因此它们可能会更改，且不遵循语义化版本控制 (semver)。虽然你可以使用它们进行快速升级，但我们强烈建议你寻找替代方案，因为它们可能会在未来的小版本更新中失效：

¥Additionally, several internal packages have been moved under the /internal sub-path. These paths are not part of our public API, so they may change without following semver. While you can use them for a quick upgrade, we strongly encourage finding replacements as they could break in future minor versions:

请访问我们 Migration.md 文件中的 合并软件包的完整列表。

¥Please visit the full list of consolidated packages in our Migration.md file.

图标系统更新

¥Icon System Updates

图标系统已更新为使用 @storybook/icons。已移除多个与图标相关的导出项：

¥The icon system has been updated to use @storybook/icons. Several icon-related exports have been removed:

- import { Icons, IconButtonSkeleton } from '@storybook/components';
+ import { ZoomIcon } from '@storybook/icons';

管理器构建器更改

¥Manager Builder Changes

管理器构建器不再为 util、assert 和 process 设置别名。如果你的插件依赖于这些包，则需要执行以下操作：

¥The manager builder no longer aliases util, assert, and process. If your addon depends on these packages, you'll need to:

1. 在插件编译时实现别名

   ¥Implement the alias at compile time in your addon

2. 更新打包配置以确保使用正确的依赖。

   ¥Update your bundling configuration to ensure correct dependencies are used

已移除对 Node.js 18 的支持

¥Node.js 18 support dropped

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

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

TypeScript 要求

¥TypeScript Requirements

Storybook 现在需要 TypeScript 4.9 或更高版本。确保你的插件与此版本兼容。

¥Storybook now requires TypeScript 4.9 or later. Ensure your addon is compatible with this version.

侧边栏组件变更

¥Sidebar Component Changes

1. 侧边栏的 Heading 组件已移除 'extra' 属性。

   ¥The 'extra' prop has been removed from the Sidebar's Heading component

2. 实验性侧边栏功能已被移除：

   ¥Experimental sidebar features have been removed:

   • experimental_SIDEBAR_BOTTOM

   • experimental_SIDEBAR_TOP

TypeScript 系统更新

¥Type System Updates

以下类型已移除：

¥The following types have been removed:

• Addon_SidebarBottomType

• Addon_SidebarTopType

• DeprecatedState

9.0.0 完整迁移指南

¥9.0.0 Full migration guide

完整的变更列表请访问 Migration.md 文件

¥For a full list of changes, please visit the Migration.md file

迁移示例

¥Migration Example

有关已更新以支持 Storybook 9.0 的插件的完整示例，请参阅 插件套件迁移 PR。合并后，它将演示现代插件开发的所有必要更改。

¥For a complete example of an addon updated to support Storybook 9.0, refer to the Addon Kit migration PR. Once merged, it will demonstrate all the necessary changes for modern addon development.

发布

¥Releasing

要支持 Storybook 9.0，我们建议你发布插件的新主版本。对于实验性功能或测试，请使用 next 标签。这允许你在发布稳定版本之前收集反馈。

¥To support Storybook 9.0, we encourage you to release a new major version of your addon. For experimental features or testing, use the next tag. This allows you to gather feedback before releasing a stable version.

支持

¥Support

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

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