Storybook 8.0 版本附加元件遷移指南

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

當我們從社群收集回饋時，我們會更新此頁面。如果您正在尋找一般性的遷移指南，我們也提供了一份通用的 Storybook 遷移指南。

更新依賴項

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

package.json

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

附加元件的重點變更

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

已移除 Node.js 16 支援

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

管理介面使用 React 18

基於 UI 的附加元件（例如，面板、工具列、分頁）依賴 React 18 在 Storybook UI 中渲染其元素。另請注意，key prop 不再傳遞到渲染函數。

不再需要 React 同級依賴

若要移除您的附加元件對 React 的同級依賴，並減少其安裝大小，請執行以下操作：

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

如需範例，請參閱我們對 Addon Kit 所做的更新。這些變更為選用項目，但建議採用。

這假設您的附加元件使用 tsup 進行打包。如果您的附加元件是使用舊版 Addon Kit（使用 Babel 打包）建置的，則必須先切換到 tsup。如需指南，請瀏覽 Addon Kit 儲存庫中實作的這些較早的變更。

@storybook/components 已棄用

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

Storybook 版面配置狀態 API 變更

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

移除已棄用的功能

8.0 版本中已移除 7.0 版本中已棄用的套件和 API。有關詳細資訊，請參閱完整的遷移注意事項。最值得注意的是，對於附加元件而言，移除 @storybook/addons 套件需要您切換到 @storybook/preview-api 和 @storybook/manager-api 以取得相同的功能。

從 Webpack 移除 Babel-loader

Storybook 8 從 webpack5 建置器中移除了 babel-loader。如果您的附加元件預設配置覆寫了 babel() 方法，則當您的使用者使用 SWC 編譯其檔案時（這是基於 Webpack 5 的 Storybook 專案的新預設配置），它將會中斷。

為了確保您的附加元件同時支援 Babel 和 SWC，您可以使用 Unplugin 建置自訂打包外掛程式，該外掛程式將適用於 Webpack 和 Vite 建置器，讓您可以完全控制在載入 stories 和元件時執行 Babel（或任何您想要執行的程式）。

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

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

遷移範例

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

package.json 用於依賴項管理、ESM 支援以及更新附加元件的進入點。
tsup.config.ts 用於打包變更，並考慮 Storybook 的全域變數。
.storybook/local-preset.js 以支援 ESM 遷移。

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

發佈

為了支援 Storybook 8.0，我們鼓勵您發佈新主要版本的附加元件，並繼續以次要或修補程式版本支援 7.x。對於實驗性功能或測試，請選擇 next 標籤。這將允許您在專案中測試您的附加元件，並在發佈穩定版本之前收集回饋。

支援

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