Storybook 8.0 的附加元件遷移指南

我們衷心感謝附加元件建立者投入的奉獻和努力，以保持 Storybook 生態系統的活力和最新狀態。隨著 Storybook 演進至 8.0 版本，帶來了新的功能和改進，本指南旨在協助您將附加元件從 7.x 遷移至 8.0。如果您需要從較早版本的 Storybook 遷移附加元件，請先參考Storybook 7.0 的附加元件遷移指南。

當我們收集社群的回饋時，我們會更新此頁面。如果您正在尋找，我們還有一個通用的Storybook 遷移指南。

更新依賴項

首先更新您的 Storybook 依賴項。使用 next 標籤取得預發佈版本、使用 latest 取得最新的穩定版本，或直接指定版本。

{
  "dependencies": {
    "@storybook/client-logger": "next" // or "latest", or "^8.0.0"
  }
}

附加元件的主要變更

以下是 8.0 版本中影響附加元件開發的重要變更。請查看完整的遷移說明，以取得 8.0 中變更的詳盡清單。

不再支援 Node.js 16

請將您的附加元件升級至 Node.js 18，因為已終止對 Node.js 16 的支援。

管理員 UI 的 React 18

基於 UI 的附加元件 (例如，面板、工具列、索引標籤) 依靠 React 18 來在 Storybook UI 中渲染其元素。另外請注意，key 屬性不再傳遞至渲染函式。

不再需要 React 對等依賴項

若要移除附加元件對 React 的對等依賴項並減少其安裝大小，請執行下列操作

將 react、react-dom 和全域化的 Storybook 套件從 peerDependencies 移至 devDependencies
將全域化套件的清單新增至 tsup 設定中的 externals 屬性，以確保它們不屬於套件的一部分。

如需範例，請參閱我們對附加元件套件所做的更新。這些變更是可選的，但建議使用。

這假設您的附加元件使用 tsup 進行套件建置。如果您的附加元件是使用較舊版本的附加元件套件 (使用 Babel 進行套件建置) 所建置，您必須先切換至 tsup。如需指南，請瀏覽在附加元件套件儲存庫中實作的這些舊變更。

@storybook/components 已棄用

現在已棄用來自 @storybook/components 的 Icons 元件，改用 @storybook/icons。此外，也已棄用各種 Button 元件屬性，並提供替代方案。

Storybook 版面配置狀態 API 變更

如果您使用 addons.setConfig({...}) 自訂 Storybook UI 設定，請注意版面配置狀態 API 的變更。

移除已棄用的功能

7.0 版本中已棄用的套件和 API 現在已在 8.0 版本中移除。請參閱完整的遷移說明以了解詳細資訊。最值得注意的是，對於 addons，移除 @storybook/addons 套件需要您切換到 @storybook/preview-api 和 @storybook/manager-api 以取得相同的功能。

從 Webpack 中移除 Babel-loader

Storybook 8 從 webpack5 建構器中移除了 babel-loader。如果您的 addon 預設覆寫了 babel() 方法，如果您的使用者使用 SWC 來編譯他們的文件（這是基於 Webpack 5 的 Storybook 專案的新預設值），它將會中斷。

為了確保您的 addon 支援 Babel 和 SWC，您可以使用 Unplugin 建立自訂的綁定外掛程式，該外掛程式將可與 Webpack 和 Vite 建構器搭配使用，讓您可以完全控制在載入 stories 和元件時執行 Babel（或任何您想要執行的內容）。

作為一種解決方案，請更新您的文件，告知使用者選擇加入 Babel 支援。這應該可以修復他們專案中的 addon，但會犧牲效能。

npx storybook@latest add @storybook/addon-webpack5-compiler-babel

Addon Kit 儲存庫已更新為支援 Storybook 8.0，您可以將其作為遷移的參考。您將看到本指南中提到的變更，包括透過 type: module 配置對 ESM 的支援。身為 addon 維護者，我們鼓勵您更新您的 addon 以包含這些變更。這簡化了設定，並讓使用者更容易將您的 addon 與最新版本的 Storybook 搭配使用。如果您選擇遵循 ESM 遷移，我們在下方準備了一份簡要的變更清單。

package.json 用於相依性管理、ESM 支援和更新 addon 的進入點。
tsup.config.ts 用於綁定變更，並考慮 Storybook 的全域變數。
.storybook/local-preset.js 以支援 ESM 遷移。

如需完整概述套用至 Addon Kit 以完全支援 Storybook 8.0 的變更，請參閱下列差異檢視。

發布

為了支援 Storybook 8.0，我們鼓勵您發布新版本的 addon 主要版本，並繼續使用次要或修補版本支援 7.x 版本。對於實驗性功能或測試，請選擇 next 標籤。這將允許您在專案中測試您的 addon，並在發布穩定版本之前收集意見反應。

支援

如果您在遵循本指南後仍然遇到 addon 的問題，請在我們的 GitHub 儲存庫中開啟新的討論。