程式碼貢獻

向 Storybook 的 monorepo 貢獻新功能或錯誤修復。本頁概述如何設定您的環境以貢獻程式碼。

先決條件

請確保您已安裝 Node 版本 18（建議：v18.16.0）。
如果您使用 Windows，請確保使用適用於 Linux 的 Windows 子系統 (WSL)。

初始設定

首先fork Storybook monorepo 並在本地端將其複製。

git clone https://github.com/your-username/storybook.git
cd storybook

Storybook 使用 Yarn 套件管理器。使用 Corepack 來設定適用於 Storybook 的正確版本。

corepack enable

執行您的第一個沙箱

Storybook 的開發發生在一組沙箱中，這些沙箱是對應於不同使用者設定的範本 Storybook 環境。在每個沙箱中，我們注入一組通用的 stories，讓我們能夠在所有這些環境中測試核心功能和擴充功能。

若要在本機端執行沙箱，您可以使用 start 命令

yarn start

它將安裝所需的先決條件、建置程式碼、根據 Vite React 設定建立和連結入門範例，最後啟動 Storybook 伺服器。

如果一切順利，您應該會看到沙箱正在執行。

Storybook sandbox running

執行不同的沙箱範本

預設情況下，start 命令設定為初始化基於 Vite 的 React 範本。如果您計劃改為處理不同的渲染器，您也可以這麼做。首先執行 task 命令，如下所示

yarn task

出現提示時，請盡可能準確地回答問題，讓 Storybook 判斷您的目標。在回答這些問題之後，您應該會看到包含您所選選項的完整命令，如果您需要重新執行該命令。

yarn task 命令採用一些開發捷徑，這些捷徑在切換分支時可能會讓您措手不及，並且可能需要您重新執行 install 和 compile 工作。您可以使用 start-from=install 旗標執行命令，來加速這個過程。

執行測試

成功執行您的第一個沙箱後，您應該在本地機器上建立一個功能完整的 Storybook 版本。在進行任何程式碼變更之前，驗證所有項目是否正常運作至關重要，特別是測試套件。

執行以下命令來執行測試

yarn test

開始開發

現在您已經驗證了您的設定，是時候開始編寫程式碼了。最簡單的方法是在一個終端機視窗中執行其中一個沙箱，並在另一個終端機中執行互動式建置流程。

假設您仍然執行在執行 yarn start 命令後初始化的基於 Vite 的 React 沙箱，請開啟一個新的終端機視窗，並導覽至 Storybook Monorepo 的 code 目錄。然後，執行以下命令，為您的貢獻建立一個新的分支

git checkout -b my-first-storybook-contribution

最後，執行以下命令來執行建置流程

yarn build

當系統提示您在 watch 模式下啟動建置流程時，請回答yes以在互動模式下進行開發。之後，選擇您要建置的套件。例如，如果您要為 @storybook/addon-docs 開發功能，您可能會想選擇 @storybook/addon-docs 和 @storybook/components。

建置的 watch 模式非常適合互動式開發。但是，為了效能考量，它只會轉換您的程式碼，而不會執行 TypeScript 編譯器。如果某些項目沒有如預期運作，請嘗試在不啟用 watch 模式的情況下執行 build 命令：它會重新產生 TypeScript 類型並為您執行自動類型檢查。

Storybook package selector

如果您要執行的工作會影響 Preview (最內層的 Storybook iframe，其中顯示故事)，它會在您儲存後一到兩秒自動重新整理。

否則，如果它會影響 Manager (最外層的 Storybook iframe，其中顯示外掛程式)，您需要在儲存後手動重新整理。

Storybook manager preview

檢查您的工作

完成程式碼編寫後，請適當新增文件和測試。這可以簡化 PR 審核流程，這表示您的程式碼會更快合併。

新增故事

在我們的套件中新增一個或一組通用故事有助於您測試您的工作。

假設您正在開發其中一個基本外掛程式，很有可能已經存在一組完整的故事。檢查外掛程式的 template/stories 目錄，其中記錄了外掛程式的運作方式，並在該處新增您的故事。

如果您正在修改與特定渲染器 (例如 React、Vue 3 等) 相關的項目，它也會有一個類似的 template/stories 目錄，您需要在其中新增您的故事。

新增測試

單元測試可確保 Storybook 不會意外中斷。如果您的程式碼可能會以不明顯的方式回歸，請在您的提取要求中包含單元測試。請使用以下命名慣例

+-- parentFolder
|   +-- [filename].ts
|   +-- [filename].test.ts

端對端測試 (e2e)

Storybook 的 Monorepo 設定為在 CI 期間依賴使用 Playwright 進行端對端測試。為了協助測試，我們鼓勵您在提交您的貢獻之前執行此測試套件。

若要針對沙箱執行 e2e 測試，您可以使用 e2e-tests 工作

yarn task --task e2e-tests --template=react-vite/default-ts --start-from=auto

如果出現問題且您想要偵錯它們，您可以傳遞 DEBUG=1 環境變數，Playwright 將在 watch 模式下執行。

DEBUG=1 yarn task --task e2e-tests --template=react-vite/default-ts --start-from=auto

提交提取要求

在提交您的貢獻之前，請使用以下命令最後一次執行測試套件

yarn test

Storybook 依靠 Vitest 作為其測試套件的一部分。在執行測試期間，如果您發現快照測試失敗，請使用 -u 旗標重新執行該命令以更新它們。

這樣做可以防止在最後一刻發生錯誤，並且是在提交提取要求後更快合併您的貢獻的好方法。如果未能這樣做，其中一位維護者會將提取要求標記為進行中，直到所有測試都通過為止。

目標 `next` 分支

測試套件完成後，是時候提交、推送並針對 Storybook 的 next (預設) 分支開啟提取要求。此分支是所有作用中開發發生的位置，並且與最新的預發行版本 (例如，7.0.0-alpha.47) 相關聯。

如果您的貢獻著重於錯誤修正，並且您希望它出現在下一個穩定版本中，請在提取要求描述中提及它。如果它看起來沒有破壞性並且修正了嚴重錯誤，我們會嘗試修補它。

使用 Fork 時的實用資源

重現作業失敗

在建立您的 PR 之後，如果其中一個 CI 作業失敗，當您檢查該作業的記錄時，您會看到它列印了一則訊息，說明如何在本地重現該工作。通常，這涉及針對正確的範本執行該工作

yarn task --task e2e-tests --template=react-vite/default-ts --start-from=install

通常，最好從 install 工作開始，以確保您的本地程式碼是完全最新的。如果您重現了失敗，您可以嘗試進行修正，使用 build 編譯它們，然後使用 --start-from=auto 重新執行該工作。

預設指示會以「連結」模式執行程式碼，這表示對 Storybook 程式庫程式碼所做的建置變更會立即反映在沙箱中 (在您下次執行該工作時)。但是，CI 會以「未連結」模式執行，在極少數情況下，其行為會有所不同。

如果您在重現時遇到問題，請嘗試使用 --no-link 旗標重新執行該命令。如果您需要這樣做，則每次變更程式碼後都需要使用 --start-from=compile 執行該命令。

如何使用重現

我們鼓勵錯誤報告包含重現步驟。如同可以在 monorepo 中針對範例專案進行互動式開發一樣，也可以針對重現儲存庫進行開發。

要這麼做，請在 monorepo 的根目錄執行以下命令

npx storybook@next link https://github.com/your-username/your-project.git

此命令會建立一個專案 ../storybook-repros/your-project，並自動將其連結到您本機的 Storybook 程式碼。連接後，您應該可以執行 Storybook 並如上述所提及的進行開發。

如果您在本機上已經有一個重現專案，您也可以使用 --local 標誌將其連結到您的 monorepo 開發設定。

npx storybook@next link --local /path/to/local-repro-directory

storybook link 命令在底層依賴 Yarn linking。它也要求您的本機重現專案使用 Yarn 2 或更高版本，如果您已經按照我們的貢獻指南，使用 storybook sandbox 命令啟用它，則情況如此。如果您嘗試連結非 Yarn 2 的專案，該過程將會失敗。

開發範本

第一步是將一個條目新增到 code/lib/cli/src/sandbox-templates.ts，這是所有重現範本的主列表。

'cra/default-js': {
    name: 'Create React App (Javascript)',
    script: 'npx create-react-app .',
    inDevelopment: true,
    expected: {
      framework: '@storybook/cra',
      renderer: '@storybook/react',
      builder: '@storybook/builder-webpack5',
    },
  },

加入 inDevelopment 旗標，直到 PR 合併（您可以接著使用第二個 PR 來移除該旗標），因為這會使開發過程變得更加容易。

key cra/default-js 由兩個部分組成

前綴是用于生成重現應用程式的工具。
後綴是修改預設安裝的選項，例如特定版本或選項。

script 欄位是產生應用程式環境的指令碼。. 引數是「目前的工作目錄」，該目錄會根據金鑰自動產生（例如，repros/cra/default-js/before-storybook）。也可以使用 {{beforeDir}} 金鑰，它將會被該目錄的路徑取代。

其餘欄位不言自明。

存在 skipTasks 欄位，因為某些沙箱可能在特定任務中暫時無法正常工作，但我們可能仍想執行其他任務。例如，在我們的控制之外引入了一個錯誤，該錯誤僅在 test-runner 任務中失敗。

name 欄位應包含範本的易讀名稱/描述。

expected 欄位反映我們預期 sb init 會產生的框架/渲染器/建構器。這在產生沙箱時對於斷言很有用。例如，如果以不同的預期框架產生範本，它將會失敗，這是一種檢測回歸的方法。

執行沙箱

如果您的範本具有 inDevelopment 旗標，則它將會在沙箱處理過程中（在本機）產生。您可以使用以下命令建立沙箱，其中 <template-key> 會被所選範本的 ID 取代，例如 cra/default-js。

yarn task --task dev --template <template-key> --start-from=install

具有 inDevelopment 的範本會自動以 --no-link 旗標執行，因為本機範本產生需要此旗標。

一旦 PR 合併，範本將會在每天晚上產生，您可以移除 inDevelopment 旗標，而沙箱將會從我們的範本儲存庫提取程式碼。

疑難排解

yarn build --all --watch 會監看所有內容，但會消耗大量資源。

事先知道您將會變更哪些套件很麻煩，而且監看它們可能會非常耗費資源，即使在現代機器上也是如此。如果您使用的機器效能足夠強大，您可以使用 yarn build --all --watch 來取代 yarn build。

了解更多關於貢獻 Storybook 的資訊

RFC 流程，用於撰寫功能請求
用於功能和錯誤修復的程式碼
框架，開始使用新的框架
文件，用於改善文件、錯字和澄清
範例，用於新的程式碼片段和範例