Storybook 8.0 遷移指南

Storybook 8 著重於改進效能、相容性和穩定性。主要功能包括：

• 🩻 透過 視覺測試外掛 的全新視覺測試工作流程
• 💨 測試建構速度快 2-4 倍、React docgen 速度快 25-50%，以及 Webpack 專案支援 SWC
• 🧩 改善框架支援：當使用非 React 渲染器時，您不再需要將 React 安裝為 peer 依賴項
• 🎛️ 加強 React 和 Vue 專案中的控制項生成
• ⚡️ 改善 Vite 架構、Vitest 測試和 Vite 5 支援
• 🌐 支援 React 伺服器元件 (RSC)：我們的實驗性解決方案可在瀏覽器中渲染非同步 RSC 並模擬 Node 程式碼
• ✨ 煥然一新的桌面 UI 和行動 UX
• ➕ 還有更多

本指南旨在協助您成功地從 Storybook 7.x 升級到 8.0！

重大變更

本指南的其餘部分將協助您成功升級，無論是自動或手動。但首先，Storybook 8 中有一些 重大變更。以下是您在繼續之前應該了解的最具影響力的變更：

• storiesOf API 已移除
• *.stories.mdx 格式已移除
• 套件已合併/移除
• 隱含動作（來自 argTypesRegex）在渲染期間（例如在 play 函數中）無法再使用
• react-docgen（而不是 react-docgen-typescript）是元件分析的預設值
• Storyshots 已移除
• 現在需要 Storybook 7 中引入的外掛 API
• 生態系統更新
  • 現在需要 Node 18+
  • 現在需要 Next.js 13.5+
  • 現在需要 Vue 3+
  • 現在需要 Angular 15+
  • 現在需要 Svelte 4+
  • 不再支援 Yarn 1

如果您的專案適用於這些變更中的任何一項，請在繼續之前閱讀連結的遷移說明。

如果任何這些新需求或變更是您專案的阻礙，我們建議您繼續使用 Storybook 7.x。

您可能希望在遷移之前閱讀完整的遷移說明。或者您可以按照以下說明進行操作，我們會盡力為您處理一切！

自動升級

要升級您的 Storybook

npx storybook@latest upgrade

這將會

1. 判斷 重大變更 中是否沒有任何一項適用於您的專案
   • 如果有的話，您將收到有關如何在繼續之前解決這些變更的說明
2. 將您的 Storybook 依賴項升級到最新版本
3. 執行一組自動遷移，這將會
   • 檢查常見的升級任務
   • 說明必要的變更，並提供更多資訊的連結
   • 要求批准，然後代表您執行任務

常見的升級問題

雖然我們會盡力自動升級您的專案，但在升級過程中，您可能會遇到一個值得一提的問題

storyStoreV7:false 和 storiesOf

如果您的 .storybook/main.js 中有 storyStoreV7: false，您需要先移除它才能升級到 Storybook 8。

如果您正在使用 storiesOf API（這在 Storybook 7 中需要 storyStoreV7: false），您需要將您的 stories 遷移到 CSF，或使用新的索引器 API 以繼續動態建立 stories。

缺少 vite.config.js 檔案

如果您正在使用 Vite，您現在可能需要在專案根目錄中建立一個 vite.config.js 檔案，以便較新版本的 Vite 可以與 Storybook 一起運作。此外，您可能需要為您的框架安裝和設定 Vite 外掛程式。更多資訊請參閱完整遷移筆記。

新專案

要將 Storybook 新增至目前未使用 Storybook 的專案

npx storybook@latest init

這將會

1. 找出您正在使用的渲染器（React、Vue、Angular、Web Components）、建構器（Webpack、Vite）或元框架（Next.js、SvelteKit）
2. 安裝 Storybook 8 並自動設定它以鏡射專案設定

手動遷移

除了上述的自動升級之外，可能還需要進行手動遷移才能使 Storybook 8 在您的專案中運作。我們已盡量縮減此清單，以方便升級。這些包括

*.stories.mdx 到 MDX+CSF

Storybook 現在要求 MDX 頁面引用以 CSF 撰寫的 stories，而不是先前的 .stories.mdx 混合方法。您可以使用以下程式碼轉換器自動轉換您的檔案（請務必更新 glob 以符合您的檔案）

# Convert stories in MDX to CSF
npx storybook@latest migrate mdx-to-csf --glob "src/**/*.stories.mdx"

如果您的 .storybook/main.js 中尚未包含新建立的 .mdx 和 .stories.js 檔案，您也需要更新您的 stories glob。

已知限制

• 程式碼轉換器不會從 .stories.mdx 檔案中移除提取的 stories。您需要手動執行此操作。

注意：此遷移支援 Storybook 6 的 「帶有 MDX 文件之 CSF stories」方法。

疑難排解

自動升級應將您的 Storybook 恢復到可運作的狀態。如果您在升級後執行 Storybook 時遇到錯誤，請執行以下操作

1. 嘗試執行 doctor 指令 以檢查常見問題（例如重複的依賴項、不相容的附加元件或不符的版本）並查看修復建議。
2. 如果您使用 dev 指令執行 storybook，請嘗試改用 build 指令。有時 build 錯誤比 dev 錯誤更易讀！
3. 查看完整遷移筆記，其中包含 Storybook 8 中值得注意的變更的詳盡列表。其中許多變更在您升級時已由自動遷移處理，但並非全部。您也可能遇到我們不了解的邊緣情況。
4. 在 GitHub 上搜尋 Storybook 問題。如果您發現問題，很可能其他人也發現了。如果是這樣，請為該問題投票、嘗試註解中描述的任何解決方法，並在您有任何有用的資訊可以貢獻時回覆。
5. 如果沒有現有問題，您可以建立一個，最好附上一個重現。我們將在穩定發布時密切關注 Storybook 8 的問題。

如果您想自己除錯，以下是一些有助於縮小問題範圍的實用方法

1. 嘗試移除所有不在 @storybook npm 命名空間中的附加元件（請確保您未移除 storybook 套件）。與 7.x 版本良好搭配使用的社群附加元件可能尚未與 8.0 相容，這是隔離該可能性最快的方法。如果您發現需要升級才能與 Storybook 8 搭配使用的附加元件，請在該附加元件的儲存庫上發布問題，或者更好的是，發出升級它的提取請求！
2. 另一種除錯技術是將 Storybook 逐步回溯到較舊的預發行版本，以找出哪個版本破壞了您的 Storybook。例如，假設 Storybook 的目前預發行版本是 8.0.0-beta.56，您可以將 package.json 中的版本設定為 8.0.0-alpha.0 並重新安裝，以驗證它是否仍然有效（alpha.0 應與 7.6.x 幾乎相同）。如果它有效，您可以嘗試 8.0.0-beta.0，然後嘗試 8.0.0-beta.28 等等。一旦您隔離了錯誤的版本，請閱讀其變更日誌條目，也許會發現哪個變更可疑。如果您發現問題，請向 Storybook monorepo 提交問題或提取請求，我們將盡力快速處理。

套件結構變更

以下套件已移除。請參閱完整遷移筆記以取得詳細資訊。

以下套件已棄用。請參閱完整遷移筆記以取得詳細資訊。

可選的遷移

除了上述的自動遷移和手動遷移之外，還有您應考慮的可選遷移。這些是我們在 Storybook 8 中已棄用的功能（但仍保持向後相容性），或是應有助於您在未來提高生產力的最佳實務。

CSF 2 到 CSF 3

將您的 stories 從 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