Storybook 分支切換器

一個 Storybook 7+ 擴充套件，用於在多個 Git 分支之間導航。同時也是一個命令列工具，可以根據每個分支自動生成一個實例。

安裝

使用 npm 安裝以下模組

npm i --save-dev storybook-branch-switcher

或使用 yarn

yarn add -D storybook-branch-switcher

然後，將以下內容新增至 .storybook/main.js

module.exports = {
  addons: ["storybook-branch-switcher"],
};

CLI

此套件導出一個名為 sb-branch-switcher 的腳本，它會根據您的 Git 工作流程自動為每個分支生成一個 Storybook 實例。(我們支援 Git 子模組，並且任何檢出操作都只會在乾淨的工作區中執行。)

設定

CLI 預設需要一個位於 .storybook/.branches.json 的設定檔。但是您可以在其他位置建立此檔案，並使用 --config 或 --c 參數將路徑傳遞給 CLI。

範例： sb-branch-switcher --config libs/storybook-host/.storybook/.branches.json

以下是所有可用選項的說明

鍵	預設值	描述
from	-	(必須) 建置後 Storybook 實例所在的位置
to	-	(必須) 所有 Storybook 實例將被複製到的位置
directory	目前資料夾	專案所在的絕對路徑
script_name	build-storybook	建置 Storybook 的 NPM 腳本名稱
default_branch	master	您的預設 Git 分支
default_root	true	將預設分支的實例複製到根資料夾
provider	-	用於檢索要處理的分支和提交的設定

使用 Bitbucket (開啟的 PR)

此供應商可讓您為 Bitbucket 儲存庫的每個開啟的 PR 生成一個 Storybook 實例(支援雲端和內部部署伺服器)。

鍵	預設值	描述
type	-	(必須) 必須是 "bitbucket"
project	-	(必須) 要鎖定的 Bitbucket 專案名稱
repository	-	(必須) 要鎖定的 Bitbucket 儲存庫名稱
url	https://bitbucket.org	要連線的 Bitbucket 主機

授權 (選用)

如果 Bitbucket 實例需要授權，您可以使用以下其中一個選項，並使用環境變數。

• 基本登入詳細資訊：BITBUCKET_USERNAME 和 BITBUCKET_PASSWORD
• 使用 HTTP Rest API 的存取權杖：BITBUCKET_TOKEN

使用 GitHub (開啟的 PR)

此供應商可讓您為 GitHub 儲存庫的每個開啟的 PR 生成一個 Storybook 實例。

鍵	預設值	描述
type	-	(必須) 必須是 "github"
owner	-	(必須) GitHub 擁有者的名稱
repository	-	(必須) 要鎖定的 Github 儲存庫名稱

您必須設定 GITHUB_TOKEN 環境變數才能存取 GitHub.com API。

使用 Gitlab (開啟的 MR)

此供應商可讓您為 Gitlab 儲存庫中的每個開啟的 MR 生成一個 Storybook 實例。

鍵	預設值	描述
projectId	-	(必須) 專案的 projectId
url	https://gitlab.com	要連線的 Gitlab 主機

您必須設定 GITLAB_TOKEN 環境變數才能存取 Gitlab.com API。

設定檔範例

{
  "from": "dist/storybook",
  "to": "dist/storybook-bundle",
  "default_branch": "master",
  "default_root": true,
  "provider": {
    "type": "bitbucket",
    "project": "my-project",
    "repository": "my-design-system"
  }
}

常見問題

如何將我的 Storybook 託管在子路徑中？ (例如 GitHub Pages)

此擴充套件開箱即用支援在根路徑託管 Storybook，但如果您想在子路徑中託管 Storybook，則需要一些額外的設定。

✅ 開箱即用：根路徑	🛠️ 需要設定：子路徑
https://127.0.0.1:6006	https://127.0.0.1:6006/some/path
https://sub.example.com	https://your-username.github.io/your-repo

只需在您的 .storybook/preview.js 檔案中進行這些變更，在此範例中，發佈到 GitHub Pages。

diff --git a/.storybook/preview.js b/.storybook/preview.js
index 6731af8..7587cb6 100644
--- a/.storybook/preview.js
+++ b/.storybook/preview.js
@@ -1,4 +1,5 @@
 /** @type { import('@storybook/react').Preview } */
 const preview = {
   parameters: {
     controls: {
@@ -10,4 +11,18 @@ const preview = {
   },
 };
 
+/* Any envvar prefixed with STORYBOOK_ will be available in the built storybook, ie. preview.js
+ * See: https://storybook.dev.org.tw/docs/configure/environment-variables
+ *
+ * Set STORYBOOK_PUBLISH_FOR_WEB=true in your build environment, along with the
+ * domain and path you'd like to host from.
+ */
+if (process.env["STORYBOOK_PUBLISH_FOR_WEB"]) {
+  preview.parameters = {
+    branches: {
+      hostname: `your-username.github.io/your-repo`,
+    }
+  }
+}
+
 export default preview;

然後，您只需在執行 sb-branch-switcher 命令的任何建置環境中設定 STORYBOOK_PUBLISH_FOR_WEB=true。

在本機測試

1. 在 .storybook/preview.js 中將 hostname 設定為 localhost:6006/storybook-bundle，
2. 透過 STORYBOOK_PUBLISH_FOR_WEB=true sb-branch-switcher <other opts> 建置
3. 執行 npx http-server dist，以在更深一層的子路徑中提供您的本機 storybook。