无需 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. 点击右上角的个人资料图标 → Settings
3. 在左侧边栏中选择“Developer settings”→“Personal access tokens”→“Tokens (classic)”
4. 点击“Generate new token”→“Generate new token (classic)”
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://[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 外，其他托管服务也可以用类似的方式自定义构建流程。