组件库模板 (Component Library Template)

这是一个基于 React + TypeScript + Vite + TailwindCSS 的组件库模板，支持发布到 npm。

功能特性

• ⚡️ 使用 Vite 进行快速构建
• 🎨 使用 TailwindCSS 进行样式设计
• 📦 支持构建为可发布的 npm 包
• 📚 集成 Storybook 用于组件文档和测试
• 🔧 TypeScript 支持，包含类型定义
• 🧪 支持 Vitest 进行单元测试

快速开始

安装依赖

npm install

开发模式

# 启动开发服务器
npm run dev

# 启动 Storybook
npm run storybook

构建

# 构建组件库（用于发布到npm）
npm run build

# 构建 Storybook
npm run build-storybook

使用方法

安装组件库

npm install component-lib-tpl

导入组件

import { Button } from 'component-lib-tpl'

function App() {
  return (
    <div>
      <Button variant="primary" size="md">
        点击我
      </Button>
    </div>
  )
}

组件说明

Button 组件

基础的按钮组件，支持多种变体和尺寸。

属性

• variant: 按钮类型 ('primary' | 'secondary' | 'outline')
• size: 按钮大小 ('sm' | 'md' | 'lg')
• disabled: 是否禁用
• onClick: 点击事件处理函数
• className: 自定义类名
• children: 按钮内容

示例

// 主要按钮
<Button variant="primary">主要按钮</Button>

// 大尺寸按钮
<Button size="lg">大按钮</Button>

// 禁用按钮
<Button disabled>禁用按钮</Button>

// 自定义点击事件
<Button onClick={() => console.log('clicked')}>
  点击我
</Button>

开发指南

添加新组件

1. 在 src/components/ 目录下创建新的组件文件夹
2. 创建组件文件 ComponentName.tsx
3. 在 src/components/index.ts 中导出新组件
4. 在 src/index.ts 中导出新组件
5. 创建对应的 Storybook 故事文件

项目结构

src/
├── components/          # 组件目录
│   ├── Button/         # Button 组件
│   │   └── Button.tsx
│   └── index.ts        # 组件统一导出
├── stories/            # Storybook 故事
│   └── Button.stories.tsx
└── index.ts           # 主入口文件

构建配置

• vite.config.ts: 用于开发和应用构建
• vite.lib.config.ts: 用于组件库构建
• 使用 vite-plugin-dts 生成 TypeScript 类型定义

📦 发布

自动发布（推荐）

项目配置了自动发布工作流，只需推送版本标签即可：

# 创建并推送版本标签
git tag v1.0.0
git push origin v1.0.0

发布工作流会自动：

• ✅ 运行测试和代码检查
• 🔨 构建项目
• 📦 发布到 npm（需要配置 NPM_TOKEN）
• 🎉 创建 GitHub Release

手动发布

如需手动发布：

1. 修改 package.json 中的包名和版本
2. 设置 private: false
3. 构建组件库：npm run build
4. 发布：npm publish --access public

详细发布指南请查看：📖 发布文档

📚 文档

📖 详细文档

查看完整的开发文档和指南。

⚙️ 构建配置说明

了解为什么要这样配置外部依赖，以及相关的最佳实践。

🔄 CI/CD

项目配置了 GitHub Actions 自动化检查，包括：

• 代码质量检查：ESLint、TypeScript 类型检查
• 构建验证：确保构建产物正确，验证外部依赖配置
• 测试运行：单元测试和覆盖率检查
• Storybook 构建：验证文档站点
• 安全审计：检查依赖安全性
• 配置验证：验证关键配置文件

每次 push 和 pull request 都会自动触发这些检查。

🚀 最佳实践

外部依赖配置

组件库正确配置了外部依赖，避免打包 React 运行时：

// vite.build.config.ts
external: ["react/jsx-runtime", ...peerDependencies]

这样做的好处：

• ✅ 减少包体积（从 300+ 行减少到 35 行）
• ✅ 避免 React 版本冲突
• ✅ 让用户控制 React 版本
• ✅ 符合组件库最佳实践

验证配置

# 构建后检查是否正确外部化
npm run build:verify

# TypeScript 类型检查
npm run typecheck

# 本地 CI 测试（模拟完整的 GitHub Actions 流程）
npm run ci:test

许可证

MIT