如何写好一个组件库

约 1416 字大约 5 分钟

组件库 CICD

2024-11-15

一、明确目标与定位

1.1 需求分析

首先，明确你的组件库要解决什么问题，面向哪些用户群体。是专注于前端 UI 框架，还是后端服务工具？理解用户需求是成功的第一步。

二、设计原则

2.1 简洁易用

保持 API 设计的简洁性，降低学习成本。文档清晰明了，示例丰富，便于快速上手。

三、编码实践

3.1 工程架构设计

参考开源组件库，采用monorepo架构，把通用的依赖都做成一个包进行单独发布，在构建组件库的过程中也可以同时产出一些实用的工具，也为后期项目的扩展打下了基础。可以采用pnpm或者lerna来实现，

组件文档可以使用vitepress生成静态文档站点

组件打包可使用esbuild把我们的组件代码导出成umd和esm模块来提供给用户使用,提供按需引入。

3.2 遵循规范

采用业界公认的编码规范和风格指南，如 eslint、prettier、styleLint、commitizen、lint-staged 等，保持代码整洁一致.

版本管理遵循 semver 语义化版本规范, 也就是 1(主版本号).0(次版本号).0(修订版本号)这样的模式。有破坏性的更新动第一位，有新功能动第二位，改改 bug 动第三位。当你完成了一个版本，但是对版本的更新内容心里没底的时候，记得先发 alpha 版本，进行生产上的反复测试。对于已经有很大用户量的项目，应该每次更新都有着 alpha, beta, rc 乃至更多的先行版本，来给正式版本提供可靠性保障。

3.3 模块化设计

将组件库拆分成多个模块，每个模块独立开发、测试、维护，便于管理和复用。

组件设计
- UI 设计
- 样式规范
- API 设计
- 文档注释

3.4 单元测试与持续集成

编写全面的单元测试，利用 Jest、GitHub action 等工具实现 CI/CD，确保代码质量。

四、运营

4.1 PR，ISSUE 规范

做一个开源项目一定会收到许多 pr 和 issue，但是很多人并不清楚仓库所有者最需要的信息是什么，为了更快的定位 bug 和解决问题，可以在 github 仓库提供 pr 和 issue 的模板来解决这一问题。也可以提供贡献指南或者开发手册，让有兴趣的人更快的可以参与进来。

五、备注（CICD）

GitHub Actions 是一个强大的工具，能够帮助你在 GitHub 上实现持续集成和持续部署（CI/CD）。下面是一个基本的指南，帮助你使用 GitHub Actions 来设置一个简单的 CI/CD 流程。

1. 创建 GitHub Actions 工作流

1.1 创建工作流文件

在你的 GitHub 仓库中，创建一个 .github/workflows 目录，并在该目录下创建一个工作流文件，比如 ci.yml。

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "16"

      - name: Install dependencies
        run: npm install

      - name: Run tests
        run: npm test

      - name: Build project
        run: npm run build

2. 配置工作流步骤

Checkout Code: 使用 actions/checkout 操作将代码检出到 runner。
Set up Node.js: 使用 actions/setup-node 操作设置 Node.js 环境。
Install Dependencies: 运行 npm install 安装项目依赖。
Run Tests: 运行 npm test 执行测试。
Build Project: 运行 npm run build 构建项目。

3. 添加持续部署（CD）

如果你想在成功构建后自动部署应用，可以添加一个部署步骤。假设你要部署到一个静态网站托管服务（例如 GitHub Pages 或 AWS S3），可以使用相应的 Action 或 CLI 工具。

示例：部署到 GitHub Pages

deploy:
  runs-on: ubuntu-latest
  needs: build

  steps:
    - name: Checkout code
      uses: actions/checkout@v3

    - name: Set up Node.js
      uses: actions/setup-node@v3
      with:
        node-version: "16"

    - name: Build project
      run: npm run build

    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./build

4. 部署到其他平台

如果你需要部署到其他平台（如 AWS、Azure、Heroku 等），可以利用相应的 GitHub Actions 或 CLI 工具。

示例：部署到 AWS S3

deploy:
  runs-on: ubuntu-latest
  needs: build

  steps:
    - name: Checkout code
      uses: actions/checkout@v3

    - name: Configure AWS credentials
      uses: aws-actions/configure-aws-credentials@v3
      with:
        aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
        aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        aws-region: us-east-1

    - name: Sync S3 bucket
      run: aws s3 sync ./build s3://your-bucket-name

如何写好一个组件库