Storybook 4 迁移指南

这个分步指南将帮助您迁移到 Storybook 4.0 (SB4)。

您来到这里可能是因为您听说了 SB4 中的所有好东西，并想知道如何升级现有项目。或者是因为您已经尝试升级但没有成功。无论哪种方式，您都来对地方了。

SB4 中最大的突破性变化是从 Webpack 3 升级到 4，以及从 Babel 6 升级到 7。因此，我们将带您完成以下步骤

1. 升级 Storybook 包
2. 处理 Webpack 4 / Babel 7 问题（如果存在）
3. 处理插件和小的突破性更改

如果本指南对您不起作用，我们还在底部提供了后续步骤 — 我们有一个很棒的社区，随时准备为您提供帮助。

注意：React Native 是另一回事，并且有其自己出色的指南。

步骤 1：包升级

首先要做的是升级您的 Storybook 包，@storybook/*。如果您使用 yarn，您可以像这样交互式升级

yarn upgrade-interactive --latest

或者如果您使用 npm，这个技巧会奏效

npx npm-check-updates '/storybook/' -u && npm install

注意：Storybook 目前需要 React 16.3 及以上版本。如果您正在开发 React 组件，这意味着您需要升级到 16.3 或更高版本才能使用 Storybook 4.0。如果您将 Storybook 用于 React 以外的任何用途，您可能无需担心这一点。

更新：我们已更新 Storybook 4.1 以恢复 React 15.x 兼容性。团队加油！

如果您运行的是旧版本的 React，您将收到的错误

core.browser.esm.js:15 Uncaught TypeError: Object(...) is not a function    at Module../node_modules/@emotion/core/dist/core.browser.esm.js (core.browser.esm.js:15)    at __webpack_require__ (bootstrap:724)    at fn (bootstrap:101)    at Module../node_modules/@emotion/styled-base/dist/styled-base.browser.esm.js (styled-base.browser.esm.js:1)    at __webpack_require__ (bootstrap:724)    at fn (bootstrap:101)    at Module../node_modules/@emotion/styled/dist/styled.esm.js (styled.esm.js:1)    at __webpack_require__ (bootstrap:724)    at fn (bootstrap:101)    at Object../node_modules/@storybook/components/dist/navigation/MenuLink.js (MenuLink.js:12)

然后尝试运行 Storybook

yarn storybook

如果浏览器打开并且一切看起来都还不错，那么您已经完成大部分工作，可以跳到步骤 3。

步骤 2：Webpack/Babel 升级

如果步骤 1 失败并且您没有在浏览器中看到 Storybook 运行，则下一步是找出原因。一个可能的罪魁祸首是 Storybook 的 Babel 7 升级。使用 Babel 6 且会中断的常见项目类型包括：create-react-app v1 (CRA1) 项目、NextJS 6 项目和 Gatsby v1 项目。

但这可能是很多原因造成的，所以让我们 выяснить 一下。如果您在终端中没有看到错误消息，请检查浏览器控制台中是否有错误消息。这是如果您的项目使用 Babel 6，您将在控制台上看到的典型 Babel 错误

{ Error: Cannot find module 'babel-loader/package.json' 
   ... long stack trace
}

如果您的项目正在运行 Babel 6，您有几个选择

1. 升级您的项目（例如 CRA 1 到 2、Next 6 到 7 或 Gatsby 1 到 2）
2. 不升级您的项目，但升级 Babel
3. 继续使用 Babel 6 并依赖 Babel 的向后兼容性。

我们建议升级到 Babel 7，除非您的项目以某种方式与 Babel 6 绑定。这是未来，所有酷孩子都在这样做。

选项 1：升级您的项目

假设您正在使用使用 Babel 6 的框架（例如 CRA1、Next6 或 Gatsby1）。获得 Storybook 4 兼容性的最佳方法是将您的项目升级到使用 Babel 7 的最新版本。Web 框架在不断改进，为什么不获得最新和最好的呢？

为此，请验证是否存在使用 Babel 7 的该项目类型的新版本。然后按照项目特定的说明进行升级。为了节省您的时间，以下是 CRA/Next/Gatsby 的链接

• 从 CRA 1 升级到 2
• Next 7 公告
• Gatsby：从 v1 迁移到 v2

注意：据我们所知，Gatsby v1 不适用于 SB4，因此升级到 v2 是您的最佳选择。

选项 2：仅升级到 Babel 7

如果由于某种原因您无法升级您的项目，您也应该能够仅使用以下命令在现有项目中升级到 Babel 7

yarn remove babel-core babel-runtime
yarn add @babel/core babel-loader --dev

如果您使用 babel 预设和插件，您也必须升级这些。Babel 是一个功能齐全的平台，并且有自己的升级指南，您可以查阅该指南以获得升级帮助。

选项 3：继续使用 Babel 6

如果由于您正在使用某些 Babel 6 特定的功能而无法升级到 Babel 7，您应该可以使用 babel-loader 7 来获得向前兼容性

yarn add babel-loader@7

还要确保您的项目中有 .babelrc，如果您选择此选项，您可能已经有了。这是 React 项目的最小配置

{ "presets": ["env", "react"] }

步骤 3：插件和“小的”突破性更改

如果您的 storybook 看起来运行正常，那么您就快要完成了！以下是您应该了解的几件事。

如果您使用任何插件，SB4 会大大提高插件的便利性。旧的 API 仍然有效，但您会收到弃用警告，并且值得花几分钟时间升级。改进之处在于

1. 不绑定到特定视图层的通用插件。
2. 由故事参数配置的插件装饰器。

通用插件

让我们首先看看通用插件。此 3.x 代码从旋钮插件的 react 特定 API 导入

import { number } from “@storybook/addon-knobs/react”;

在 SB4 中，这变为

import { number } from “@storybook/addon-knobs”;

更好，对吧？而且这是一个简单的修复。有关更多信息，请参阅完整的迁移文档。

故事参数

现在让我们看一下带有故事参数的插件装饰器。SB4 引入了故事参数，我们已更新所有核心插件以使用它们。

在 3.x 中，使用插件像包装函数一样实现

storiesOf('My component', module)
  .add('story1', withNotes('some notes')(() => <Component ... />))
  .add('story2', withNotes('other notes')(() => <Component .../>))

现在在 4.0 中，这变为

// .storyook/config.js (global decorator, local also supported)
addDecorator(withNotes)

// Component.stories.js
storiesOf('My component', module)
  .add('story1', () => <Component />, { notes: 'some notes' })
  .add('story2', () => <Component />, { notes: 'other notes' })

故事参数直接对应于旧的 withX 参数，因此很容易迁移您的代码。有关更多信息，请参阅完整的迁移文档。

小的突破性更改

除了更新您的插件外，还有一些小的突破性更改您应该了解。如果其中任何一项适用于您的项目，则只需进行最小的更新即可修复。

这是一个清单，可帮助您快速更新

✅ 您使用键盘快捷键吗？我们在 SB4 中改进了它们。

✅ 您使用 addon-info 吗？我们已删除 addWithInfo。

✅ 您使用 addon-knobs 吗？我们更改了 其 select 行为 以及 它如何保存 URL。

✅ 您使用 addon-storyshots 吗？您应该了解一些 API 更改。特别是如果您使用 webpack 的 require.context 包含故事，您将需要 babel-plugin-require-context-hook。

✅ 您在 CI 中运行 storybook 吗？start-storybook 现在会弹出一个浏览器，但您可以使用 --ci 标志禁用此功能。

✅ 您将 Typescript 与 ts-loader 一起使用吗？如果是这样，您可能需要将其升级到支持 webpack 4 的 4.0 之后的版本。

✅ 您使用 getstorybook CLI 吗？我们改进了 CLI，现在您可以使用 sb init 初始化一个新项目。

就这样！还不错，对吧？

结束了！

希望此时您已成功升级到 SB4。如果是这样，恭喜您，欢迎来到组件开发的未来！

如果您在阅读本指南时遇到问题，或者已阅读完本指南但仍有问题，请采取以下步骤

1. 在我们的 Github 问题中搜索您的问题 — 其他人可能遇到过同样的问题。
2. 创建一个新问题，描述您的问题，最好提供一个公共仓库的链接，我们可以在其中重现该问题。
3. 加入我们的公共 Discord，并在 #support 频道上提问。我们是一个友好的社区，希望帮助您升级。

— 来自 Storybook 团队的 ❤️