如何在不使用 npm 的情況下共享私有 Astro 元件

元件的共享與管理

在網頁開發中，偶爾會遇到想在多個網站重複使用相同 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. 點擊右上角的個人資料圖示 → Settings
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://[email protected]/$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. 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 儀表板 → your-project → Settings → Build & deployments
   • 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 以外，其他託管服務也能用類似的方式自訂建置流程。