Topics

元件共享管理

在 Web 開發中，很少會出現需要在多個網站上重複使用相同的 UI 元件的情況，對嗎？

如果您想使用 Astro 這樣的現代框架簡化多個網站的開發，共享元件庫非常有效。但是，如果您將組件以 npm 套件的形式共用，發布私人包需要付費計劃你會需要它的。

這次，我們將介紹一種使用 GitHub 儲存庫和 Cloudflare Pages 高效共享和管理元件的方法，而無需使用 npm 打包它們！

組件共享面臨哪些挑戰？

• 我想在多個 Astro 網站上使用相同的 UI 元件！
• 我想使用 Cloudflare Pages 託管！
• 我想在 GitHub 上的私人儲存庫中管理元件！
• 我想將我的組件打包為 npm 包，但我不想將其公開！

看起來是這樣的。那你該怎麼做呢？

使用 GitHub 儲存庫和自訂建置腳本解決

為了解決這些問題，我認為嘗試這樣的方法是個好主意：

1. 為您的元件建立一個 GitHub 儲存庫
2. 使用文件引用進行本機開發
3. Cloudflare Pages 環境在建置時複製元件儲存庫

這允許您共用和管理元件，而無需使用私人 npm 套件。

實現如下

1. 建立 GitHub 個人存取令牌

建立 GitHub 個人存取權杖來存取您的私人儲存庫。

1. 登入 GitHub
2. 點選右上角的個人資料圖示→設置
3. 從左側邊欄選擇“開發者設定”→“個人存取權杖”→“令牌（經典）”
4. 點選“產生新代幣”→“產生新代幣（經典）”
5. 授予令牌以下權限：
   • repo- 完全存取私人儲存庫
6. 產生一個令牌並將其儲存在安全的地方（它只會顯示一次）

2. 建置元件庫

為您的元件建立一個 GitHub 儲存庫（例如github.com/your-username/ui-components）。

元件庫 package.json

{
  "name": "@your-org/components",
  "private": true,
  "type": "module",
  "main": "src/index.ts",
  "exports": {
    ".": "./src/index.ts"
  },
  "files": [
    "src"
  ],
  "peerDependencies": {
    "astro": "^5.7.12"
  }
}

3.設定主項目

配置主項目的 package.json 以使用該元件。

主項目 package.json

{
  "name": "your-astro-project",
  "type": "module",
  "private": true,
  "config": {
    "componentVersion": "v1.0.0",
    "orgName": "your-username",
    "repoName": "ui-components",
    "namespace": "your-org",
    "packageName": "components"
  },
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro",
    "setup-components": "set -e; ORG_NAME=\\\\"$npm_package_config_orgName\\\\"; REPO_NAME=\\\\"$npm_package_config_repoName\\\\"; NAMESPACE=\\\\"$npm_package_config_namespace\\\\"; PACKAGE_NAME=\\\\"$npm_package_config_packageName\\\\"; VERSION=\\\\"$npm_package_config_componentVersion\\\\"; mkdir -p temp; git clone -b $VERSION <https://$GITHUB_TOKEN@github.com/$ORG_NAME/$REPO_NAME.git> temp/$REPO_NAME; mkdir -p node_modules/@$NAMESPACE; ln -sf $(pwd)/temp/$REPO_NAME node_modules/@$NAMESPACE/$PACKAGE_NAME",
    "build-with-components": "npm run setup-components && npm run build"
  },
  "dependencies": {
    "@your-org/components": "file:../ui-components"
  },
  "devDependencies": {
    // Astroなどの開発依存関係
  }
}

以下四點是關鍵。

1. 配置部分：元件庫資訊集中管理
2. 安裝組件腳本：在建置時從 GitHub 克隆元件
3. 使用組件建置腳本：結合組件的設定和建構的命令
4. dependencies：本地開發的文件引用

4. 設定本機開發環境

將元件庫克隆到與您的專案相同的目錄中，並將其用作檔案引用。

projects/
├── ui-components/ # 元件庫
└── your-astro-project/ # 主項目

您在本機開發時對元件所做的任何變更都會立即反映在您的主專案中。

5. 設定 Cloudflare 頁面

以下是在 Cloudflare Pages 上進行設定的方法。

1. 設定環境變數:
   • 頁面儀表板 → 您的項目 → 設定 → 環境變數
   • 變數名：GITHUB_TOKEN
   • 值：您建立的 GitHub 個人存取權令牌
2. 配置建置命令:
   • 頁面儀表板 → 您的專案 → 設定 → 建置與部署
   • Build command: npm run build-with-components
   • Build output directory: dist(預設)

元件庫的指定版本將在建置時自動克隆並包含。

設定完成後，組件即可輕鬆使用

一旦配置完成，使用該組件就非常容易。

在元件庫中src/index.ts並導出組件。

export { default as Button } from './components/base/Button.astro';
export { default as Heading } from './components/base/Heading.astro';
// 他のコンポーネントもここでエクスポート

匯入您想要在主專案中使用的元件。

---
import { Button, Heading } from '@your-org/components';
---

<div>
  <Heading>Hello World</Heading>
  <Button>Click me</Button>
</div>

那麼版本控制怎麼樣呢？

當你想要發布元件庫的新版本時，

1. 對組件庫進行更改並提交
2. 建立一個新標籤（例如v1.1.0）
3. 更新主項目中的 package.json

   "config": {
     "componentVersion": "v1.1.0",
     // 他の設定...
   }
   
   

每個項目都可以使用它所需的元件版本。

開發流程也很安全

開發流程安全高效，需要擔心的事情更少，這很好。

1. 開發新功能或改進元件庫（例如feature/new-button分支）
2. 您可以立即在主專案中測試並驗證本機環境中的變更。
3. 一旦開發進展到某個階段，就建立一個測試標籤（例如v1.1.0-test）
4. 在主項目的測試分支中componentVersion更新到測試標籤並部署到測試環境
5. 一旦確認測試環境沒有問題，就將其合併到元件庫主分支。
6. 透過建立新版本標籤並更新主專案中的版本（例如）將其推送到生產環境。v1.1.0）

關鍵在於您可以在不影響生產環境的情況下測試組件變更！

Cloudflare Pages 生產環境config.componentVersion因為它使用在config您可以放心，這些變更不會影響您的生產環境，除非您更新

■ 結合 GitHub 私人儲存庫和自訂建置腳本，無需使用私人 npm 套件！

■ 正確管理 GitHub Tokens 並正確配置本機開發環境可實現整個團隊的無縫元件共用！

你怎麼認為？

非常適合中小型團隊和具有成本效益的專案。

將來，隨著我們團隊和專案的發展，我們可能會考慮遷移到 npm 私有包，但就目前而言，我們認為這種方法提供了一種足夠有效的共享元件的方法！

補充：這也可以應用於 Astro 以外的框架（React、Vue、Svelte 等）。配置細節可能有所不同，但基本方法相同！即使使用 Cloudflare Pages 以外的託管服務，您也可以以類似的方式自訂建置流程。