无需使用 npm 即可共享私有 Astro 组件的方法

组件共享管理

在 Web 开发中，有时需要在多个网站上重复使用相同的 UI 组件，对吧？

使用 Astro 等现代框架开发多个网站以提高效率时，组件库共享非常有效。但是，将组件作为 npm 包共享时，发布私有包需要付费计划。

本次我们将介绍如何使用 GitHub 仓库和 Cloudflare Pages，在无需通过 npm 打包的情况下，高效地共享和管理组件！

组件共享有什么问题？

• 想要在多个 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://$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 仪表盘 → 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 以外的托管服务中，也能以类似的方式自定义构建流程。