Storybook 9.0 插件迁移指南

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

替换依赖项

许多先前发布的包已移至 Storybook 的核心部分。如果您的插件依赖于这些包中的任何一个，您应该将它们从您的 package.json 中移除，并更新您的插件以便从新位置导入。如果您的插件尚不依赖 storybook 包，您应该将其添加到您的 package.json 中作为依赖项。

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

依赖管理

在 Storybook 9.0 中，大多数 Storybook 包已整合到主包 storybook 中。这意味着您不再需要将单个 Storybook 包作为依赖项引用。相反，您应该在插件的 package.json 中将 storybook 定义为对等依赖 (peer dependency)。

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

这种方法确保了

1. 您的插件使用与宿主项目相同版本的 Storybook API
2. 您可以在最终打包中避免重复的 Storybook 包
3. 您的插件包大小被最小化

如果您的插件支持 Storybook 的多个主要版本，您可以在对等依赖项中指定更宽的版本范围

{
  "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 新主要版本的发布，同步发布您的插件的新主要版本。这种做法

1. 使您的代码更容易维护
2. 让您能够利用新的功能和改进
3. 为您的用户提供更清晰的升级路径

插件的主要变更

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

包整合

多个包已整合到主包 storybook 中。请更新您的导入以使用新的路径

此外，一些内部包已移至 /internal 子路径下。这些路径不属于我们的公共 API，因此可能会在不遵循语义化版本（semver）的情况下发生变化。虽然您可以暂时使用它们进行快速升级，但我们强烈建议寻找替代方案，因为它们可能在未来的次要版本中发生中断。

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

图标系统更新

图标系统已更新为使用 @storybook/icons。一些与图标相关的导出已被移除

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

管理器构建器变更

管理器构建器不再别名化 util, assert, 和 process。如果您的插件依赖于这些包，您需要

1. 在插件的编译时实现别名
2. 更新您的打包配置以确保使用了正确的依赖项

已移除对 Node.js 18 的支持

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

TypeScript 要求

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

侧边栏组件变更

1. 侧边栏的 Heading 组件已移除 'extra' 属性
2. 实验性侧边栏功能已移除
   • experimental_SIDEBAR_BOTTOM
   • experimental_SIDEBAR_TOP

类型系统更新

以下类型已被移除

• Addon_SidebarBottomType
• Addon_SidebarTopType
• DeprecatedState

9.0.0 完整迁移指南

有关完整的变更列表，请访问我们 Migration.md 文件中Migration.md 文件

迁移示例

有关更新到支持 Storybook 9.0 的插件的完整示例，请参阅 Addon Kit 迁移 PR。一旦合并，它将展示现代插件开发所需的所有必要变更。

发布

为了支持 Storybook 9.0，我们鼓励您发布插件的新主要版本。对于实验性功能或测试，请使用 next 标签。这使您可以在发布稳定版本之前收集反馈。

支持

如果您在按照本指南操作后插件遇到问题，请在我们的 GitHub 仓库中发起新的讨论。