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 以外的托管服务，您也可以以类似的方式自定义构建流程。