加入直播:周四,美国东部时间上午 11 点,Storybook 9 发布及 AMA
文档迁移到 9.0
Storybook Docs

Storybook 9.0 迁移指南

Storybook 9 提高了性能、兼容性和稳定性。其关键特性包括

  • 🔋 Storybook Test,Storybook 中内置的一体化测试工具
  • 🧪 组件测试
  • ♿️ 可访问性测试
  • 🛡️ 测试覆盖率
  • 🪶 包体积减小 48%
  • ⚛️ 用于设备和 web 的 React Native
  • 🏷️ 基于标签的故事组织

本指南旨在帮助您成功地将 Storybook 从 8.x 升级到 9.0

要从 8 之前的 Storybook 版本迁移?

您需要先升级到 Storybook 8。然后您可以返回本指南。

主要破坏性变更

本指南的其余部分将帮助您成功升级,无论是自动还是手动。但首先,Storybook 9 中有一些破坏性变更。在您继续之前,这里有一些您应该了解的最具影响力的变更

如果您的项目适用于任何这些变更,请在继续之前阅读链接的迁移说明。

如果这些新要求或变更对您的项目造成阻碍,我们建议您继续使用 Storybook 8.x。

您可能希望在迁移之前阅读完整的迁移说明。或者您可以运行下面的升级命令,我们将尽力为您处理所有事情!

自动升级

升级您的 Storybook

npx storybook@next upgrade

这将

  1. 确定没有破坏性变更适用于您的项目
    • 如果适用,您将收到有关如何在继续之前解决它们的说明
  2. 将您的 Storybook 依赖项升级到最新版本
  3. 运行一系列*自动迁移*,这将
    • 检查常见的升级任务
    • 解释必要的变更并提供更多信息的链接
    • 请求批准,然后代表您自动执行任务

正在迁移 monorepo 项目?请确保在包含 storybook 包的当前工作目录 (cwd) 中运行该命令。

一些对 monorepos 有用的命令

  • 对于 NX 项目,您可以使用 nx migrate 命令
  • --config-dir CLI 标志可用于指定与默认 ./.storybook 目录不同的配置目录

新项目

要将 Storybook 添加到当前未使用 Storybook 的项目中

npm create storybook@latest

这将

  1. 确定您正在使用的渲染器(React、Vue、Angular、Web Components)、构建器(Webpack、Vite)或元框架(Next.js、SvelteKit)
  2. 安装 Storybook 9 并自动配置它以镜像项目设置

故障排除

自动升级应该能让您的 Storybook 进入工作状态。如果您在升级后运行 Storybook 时遇到错误,请执行以下操作

  1. 尝试运行doctor 命令来检查常见问题(例如重复的依赖项、不兼容的插件或版本不匹配)并查看修复建议。
  2. 如果您使用 dev 命令运行 storybook,请尝试改用 build 命令。有时 build 错误比 dev 错误更容易理解!
  3. 检查完整的迁移说明,其中包含 Storybook 9 中值得注意的变更的完整列表。许多这些变更在您升级时已通过自动迁移处理,但并非所有都已处理。您也可能遇到了我们不知道的边缘情况。
  4. GitHub 上搜索 Storybook 问题。如果您遇到了问题,很有可能其他人也遇到了。如果是这样,请给该问题点赞,尝试评论中描述的任何临时解决方案,如果您有有用的信息要贡献,请回帖。
  5. 如果不存在现有问题,您可以创建一个,最好附带一个重现步骤。在 Storybook 9 版本稳定期间,我们将密切关注相关问题。

如果您更喜欢自己调试,以下是一些有助于缩小问题范围的有用方法

  1. 尝试移除所有不在 @storybook npm 命名空间中的插件(确保您没有移除 storybook 包)。与 8.x 配合良好的社区插件可能尚未与 9.0 兼容,这是隔离这种可能性最快的方法。如果您发现需要升级才能与 Storybook 9 配合使用的插件,请在该插件的仓库中发布问题,或者更好的是,提交一个升级它的拉取请求!
  2. 另一种调试技巧是二分法寻找旧的预发布版本,以确定是哪个版本导致您的 Storybook 出现问题。例如,假设 Storybook 当前的预发布版本是 9.0.0-beta.56,您可以在 package.json 中将版本设置为 9.0.0-alpha.0 并重新安装以验证它是否仍然工作(alpha.0 应该与 8.6.x 几乎相同)。如果它工作,您可以尝试 9.0.0-beta.0,然后是 9.0.0-beta.28 等等。一旦您找到了有问题的版本,阅读其CHANGELOG 条目,也许会有一个变更让您觉得它是罪魁祸首。如果您找到了问题,请向 Storybook monorepo 提交问题或拉取请求,我们将尽力快速解决。

包结构变更

以下软件包不再发布。相反,它们已合并到 Storybook 的核心包 storybook 中。如果合并后的包有导出,则可以通过下表中的替换路径使用。有关详细信息,请参阅完整的迁移说明

移除替换
@storybook/addon-actionsstorybook/actions
@storybook/addon-backgrounds不适用
@storybook/addon-controls不适用
@storybook/addon-highlightstorybook/highlight
@storybook/addon-interactions不适用
@storybook/addon-measure不适用
@storybook/addon-outline不适用
@storybook/addon-toolbars不适用
@storybook/addon-viewportstorybook/viewport
@storybook/manager-apistorybook/manager-api
@storybook/preview-apistorybook/preview-api
@storybook/teststorybook/test
@storybook/themingstorybook/theming

以下软件包已合并并移至内部路径,以表明它们现在仅供内部使用。它们将在 9.x 版本中继续工作,但很可能在 10.0 中移除。有关详细信息,请参阅完整的迁移说明

已弃用替换
@storybook/builder-managerstorybook/internal/builder-manager
@storybook/channelsstorybook/internal/channels
@storybook/client-loggerstorybook/internal/client-logger
@storybook/componentsstorybook/internal/components
@storybook/core-commonstorybook/internal/common
@storybook/core-eventsstorybook/internal/core-events
@storybook/core-serverstorybook/internal/core-server
@storybook/csf-toolsstorybook/internal/csf-tools
@storybook/docs-toolsstorybook/internal/docs-tools
@storybook/managerstorybook/internal/manager
@storybook/node-loggerstorybook/internal/node-logger
@storybook/previewstorybook/internal/preview
@storybook/routerstorybook/internal/router
@storybook/telemetrystorybook/internal/telemetry
@storybook/typesstorybook/internal/types

插件作者可以继续使用内部软件包,目前还没有任何替代方案。

可选迁移

除了上述的自动迁移和手动迁移外,还有一些您应该考虑的可选迁移。这些是我们已在 Storybook 9 中弃用(但仍保持向后兼容),或将帮助您在未来提高生产力的最佳实践。

test-runneraddon-vitest

addon-vitest 以及其余的Storybook Test 体验旨在取代 test-runner。它更快,并提供更好的编写和运行测试的体验。如果您的项目使用 React、Vue 或 Svelte 并使用 Vite 构建,您应该考虑迁移到 addon-vitest,按照安装说明进行操作。

CSF 2 到 CSF 3

将故事从 CSF 2 转换为 CSF 3 有很多好处。我们提供了一个 codemod,在大多数情况下,它应该自动为您更改代码(确保更新 glob 以匹配您的文件)

# Convert CSF 2 to CSF 3
npx storybook@latest migrate csf-2-to-3 --glob="**/*.stories.tsx" --parser=tsx