Storybook 9.0 迁移指南
Storybook 9 提高了性能、兼容性和稳定性。其关键特性包括
- 🔋 Storybook Test,Storybook 中内置的一体化测试工具
- 🧪 组件测试
- ♿️ 可访问性测试
- 🛡️ 测试覆盖率
- 🪶 包体积减小 48%
- ⚛️ 用于设备和 web 的 React Native
- 🏷️ 基于标签的故事组织
本指南旨在帮助您成功地将 Storybook 从 8.x 升级到 9.0!
要从 8 之前的 Storybook 版本迁移?
您需要先升级到 Storybook 8。然后您可以返回本指南。
主要破坏性变更
本指南的其余部分将帮助您成功升级,无论是自动还是手动。但首先,Storybook 9 中有一些破坏性变更。在您继续之前,这里有一些您应该了解的最具影响力的变更
- 软件包已合并/移除
- 核心插件移至核心
- 测试插件从
experimental-addon-test
重命名为addon-vitest
nextjs-vite
框架已稳定- 为了支持 Vite,移除了 Webpack 对 Preact、Vue 和 Web Components 构建器的支持
- Manager 构建器移除了
util
、assert
和process
的别名 - 生态系统更新
如果您的项目适用于任何这些变更,请在继续之前阅读链接的迁移说明。
如果这些新要求或变更对您的项目造成阻碍,我们建议您继续使用 Storybook 8.x。
您可能希望在迁移之前阅读完整的迁移说明。或者您可以运行下面的升级命令,我们将尽力为您处理所有事情!
自动升级
升级您的 Storybook
npx storybook@next upgrade
这将
- 确定没有破坏性变更适用于您的项目
- 如果适用,您将收到有关如何在继续之前解决它们的说明
- 将您的 Storybook 依赖项升级到最新版本
- 运行一系列*自动迁移*,这将
- 检查常见的升级任务
- 解释必要的变更并提供更多信息的链接
- 请求批准,然后代表您自动执行任务
正在迁移 monorepo 项目?请确保在包含 storybook
包的当前工作目录 (cwd
) 中运行该命令。
一些对 monorepos 有用的命令
- 对于 NX 项目,您可以使用
nx migrate
命令 --config-dir
CLI 标志可用于指定与默认./.storybook
目录不同的配置目录
新项目
要将 Storybook 添加到当前未使用 Storybook 的项目中
npm create storybook@latest
这将
- 确定您正在使用的渲染器(React、Vue、Angular、Web Components)、构建器(Webpack、Vite)或元框架(Next.js、SvelteKit)
- 安装 Storybook 9 并自动配置它以镜像项目设置
故障排除
自动升级应该能让您的 Storybook 进入工作状态。如果您在升级后运行 Storybook 时遇到错误,请执行以下操作
- 尝试运行
doctor
命令来检查常见问题(例如重复的依赖项、不兼容的插件或版本不匹配)并查看修复建议。 - 如果您使用
dev
命令运行storybook
,请尝试改用build
命令。有时build
错误比dev
错误更容易理解! - 检查完整的迁移说明,其中包含 Storybook 9 中值得注意的变更的完整列表。许多这些变更在您升级时已通过自动迁移处理,但并非所有都已处理。您也可能遇到了我们不知道的边缘情况。
- 在GitHub 上搜索 Storybook 问题。如果您遇到了问题,很有可能其他人也遇到了。如果是这样,请给该问题点赞,尝试评论中描述的任何临时解决方案,如果您有有用的信息要贡献,请回帖。
- 如果不存在现有问题,您可以创建一个,最好附带一个重现步骤。在 Storybook 9 版本稳定期间,我们将密切关注相关问题。
如果您更喜欢自己调试,以下是一些有助于缩小问题范围的有用方法
- 尝试移除所有不在
@storybook
npm 命名空间中的插件(确保您没有移除storybook
包)。与 8.x 配合良好的社区插件可能尚未与 9.0 兼容,这是隔离这种可能性最快的方法。如果您发现需要升级才能与 Storybook 9 配合使用的插件,请在该插件的仓库中发布问题,或者更好的是,提交一个升级它的拉取请求! - 另一种调试技巧是二分法寻找旧的预发布版本,以确定是哪个版本导致您的 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-actions | storybook/actions |
@storybook/addon-backgrounds | 不适用 |
@storybook/addon-controls | 不适用 |
@storybook/addon-highlight | storybook/highlight |
@storybook/addon-interactions | 不适用 |
@storybook/addon-measure | 不适用 |
@storybook/addon-outline | 不适用 |
@storybook/addon-toolbars | 不适用 |
@storybook/addon-viewport | storybook/viewport |
@storybook/manager-api | storybook/manager-api |
@storybook/preview-api | storybook/preview-api |
@storybook/test | storybook/test |
@storybook/theming | storybook/theming |
以下软件包已合并并移至内部路径,以表明它们现在仅供内部使用。它们将在 9.x
版本中继续工作,但很可能在 10.0
中移除。有关详细信息,请参阅完整的迁移说明。
已弃用 | 替换 |
---|---|
@storybook/builder-manager | storybook/internal/builder-manager |
@storybook/channels | storybook/internal/channels |
@storybook/client-logger | storybook/internal/client-logger |
@storybook/components | storybook/internal/components |
@storybook/core-common | storybook/internal/common |
@storybook/core-events | storybook/internal/core-events |
@storybook/core-server | storybook/internal/core-server |
@storybook/csf-tools | storybook/internal/csf-tools |
@storybook/docs-tools | storybook/internal/docs-tools |
@storybook/manager | storybook/internal/manager |
@storybook/node-logger | storybook/internal/node-logger |
@storybook/preview | storybook/internal/preview |
@storybook/router | storybook/internal/router |
@storybook/telemetry | storybook/internal/telemetry |
@storybook/types | storybook/internal/types |
插件作者可以继续使用内部软件包,目前还没有任何替代方案。
可选迁移
除了上述的自动迁移和手动迁移外,还有一些您应该考虑的可选迁移。这些是我们已在 Storybook 9 中弃用(但仍保持向后兼容),或将帮助您在未来提高生产力的最佳实践。
test-runner
到 addon-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