Storybook 8.0 遷移指南

Storybook 8 著重於改善效能、相容性與穩定性。主要功能包含

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

本指南旨在協助您順利地從 Storybook 7.x 升級至 8.0！

重大變更

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

• storiesOf API 已移除
• *.stories.mdx 格式已移除
• 套件已整合/移除
• 隱式 actions（來自 argTypesRegex）在渲染期間（例如在 play function 中）無法再使用
• 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 的專案

npm create storybook@latest

這將會

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 混合方法。您可以使用下列 codemod 自動轉換您的檔案（請務必更新 glob 以符合您的檔案）

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

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

已知限制

• codemod 不會從 .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 搭配運作的擴充套件，請在該擴充套件的儲存庫上發布問題，或更好的是，提交 pull request 來升級它！
2. 另一種偵錯技術是二分搜尋到較舊的 Storybook 預發布版本，以找出哪個版本破壞了您的 Storybook。例如，假設目前 Storybook 的預發布版本為 8.0.0-beta.56，您可以將版本設定為 8.0.0-alpha.0 在您的 package.json 中並重新安裝，以驗證它是否仍然運作（alpha.0 應與 7.6.x 幾乎相同）。如果它運作，您可以嘗試 8.0.0-beta.0，然後 8.0.0-beta.28 等等。一旦您隔離了錯誤的版本，請閱讀其 更新日誌條目，也許有一個變更跳出來成為罪魁禍首。如果您找到問題，請提交問題或 pull request 給 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