不使用 npm 共享私密 Astro 元件的方法

元件共享管理

在 Web 開發中，有時會需要在多個網站間重複使用相同的 UI 元件，對吧？

使用 Astro 等現代化框架進行多站點開發時，共享元件庫是非常有效的做法。但是，將元件作為 npm 套件共享時，發布私密套件需要付費方案，這確實是個問題。

本次我們將為您介紹一種不透過 npm 打包、而是使用 GitHub 儲存庫與 Cloudflare Pages 來高效地共享和管理元件的方法！

元件共享面臨的課題是什麼？

• 想在多個 Astro 網站使用相同的 UI 元件！
• 想在 Cloudflare Pages 上進行託管！
• 想在 GitHub 私有儲存庫中管理元件！
• 想把元件打包成 npm 套件，但不想公開！

就是這樣的狀況。那該怎麼辦才好呢？

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

為了解決這些課題，我們建議採取以下這樣的做法。

1. 為元件建立 GitHub 儲存庫
2. 本地開發時使用檔案參考
3. 在 Cloudflare Pages 環境中於建置時複製元件儲存庫

不用 npm 私有套件，也能實現元件的共享和管理。

實作大概是這樣

1. 建立 GitHub Personal Access Token

建立 GitHub Personal Access Token 以存取私人儲存庫。

1. 登入 GitHub
2. 點擊右上方的個人檔案圖示 → 設定
3. 在左側邊欄中選擇「Developer settings」→「Personal access tokens」→「Tokens (classic)」
4. 點擊「Generate new token」→「Generate new token (classic)」
5. 授予 token 以下權限：
   • repo - 對私人儲存庫的完整存取權限
6. 生成 token，並將其保存在安全的位置（只會顯示一次）

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などの開発依存関係
  }
}

以下 4 點至關重要。

1. config 區段：統一管理元件庫資訊
2. setup-components 指令碼：建置時從 GitHub 克隆元件
3. build-with-components 指令碼：結合元件設定和建置的指令
4. dependencies：本機開發用的檔案參考

4. 設定本地開發環境

將元件庫克隆到與專案相同的層級，並透過檔案參考來使用。

projects/
  ├── ui-components/         # コンポーネントライブラリ
  └── your-astro-project/     # メインプロジェクト

在本地開發期間修改元件時，變更會立即反映在主專案中。

5. Cloudflare Pages 設定

Cloudflare Pages 的設定如下。

1. 環境變數設定:
   • Pages 儀表板 → your-project → Settings → Environment variables
   • 變數名稱: GITHUB_TOKEN
   • 值: 建立的 GitHub Personal Access Token
2. 建置命令設定:
   • Pages 儀表板 → 您的專案 → 設定 → 建置與部署
   • Build command: npm run build-with-components
   • 建置輸出目錄：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. 確認測試環境中沒有問題後，合併至元件庫的 main 分支
6. 建立新的版本標籤，並更新主專案的版本以反映到生產環境（例如：v1.1.0）

可以在不影響生產環境的情況下測試元件變更，這就是重點！

Cloudflare Pages 的生產環境使用 config.componentVersion 指定的標籤版本，因此只要不建立新標籤並更新 config，變更就不會影響生產環境，非常安心！

■ 無需使用 npm 私有套件，結合 GitHub 私有儲存庫與自訂建置指令碼！

■ 透過正確管理 GitHub Token 和設定本地開發環境，實現整個團隊無縫的元件共享！

如何呢？

對於小型到中型的團隊，或重視成本效益的專案，這不是最佳選擇嗎？

將來如果團隊或專案規模成長，也可以考慮遷移至 npm 私有套件，但在目前階段，這種方法已足以實現高效的元件共享！

補充說明：除了 Astro 之外，其他框架（React、Vue、Svelte 等）也可以應用此方法。設定細節可能有所不同，但基本方法相同！除了 Cloudflare Pages 之外，其他主機服務也可以用類似的方法自訂建置流程。