Bear 组件库

一个轻量级、可扩展的 React 组件库，用于演示如何构建、发布和替换 npm 包中的关键组件。这个项目展示了组件库的标准结构和最佳实践。

📋 项目概述

Bear 组件库是一个演示项目，旨在展示如何：

• 构建一个标准化的 React 组件库
• 使用 TypeScript 提供完整的类型支持
• 使用 Rollup 打包并生成多种模块格式
• 发布到 npm 并在其他项目中使用
• 替换和扩展核心组件

该库目前包含两个基础组件类型（按钮和文本），但其架构设计允许轻松添加更多组件。

🚀 安装

# 使用 npm
npm install bear-component-library

# 使用 yarn
yarn add bear-component-library

# 使用 pnpm
pnpm add bear-component-library

⚙️ 配置说明

在项目中引入

Bear 组件库支持多种模块格式，可以在不同的项目环境中使用：

• ES Modules (推荐): 支持树摇（tree-shaking）优化
• CommonJS: 适用于 Node.js 环境或旧版构建系统

// 使用 ES Modules
import { RedButton, LargeText } from 'bear-component-library';

// 使用 CommonJS
const { RedButton, LargeText } = require('bear-component-library');

TypeScript 支持

组件库包含完整的 TypeScript 类型定义，无需额外安装类型包：

import { ButtonProps, TextProps } from 'bear-component-library';

// 使用类型
const customProps: ButtonProps = {
  label: '自定义按钮',
  buttonType: 'red',
  size: 'large',
  onClick: () => console.log('点击了按钮')
};

🔄 核心组件替换

Bear 组件库设计为可扩展和可替换的，支持通过继承、组合或重新导出等方式替换核心组件。详细的替换方法请参考源代码中的类型定义和组件实现。

📝 使用方法

组件库提供了按钮和文本两种基础组件，可以根据需要进行导入和使用。详细的API文档请参考源代码中的类型定义文件。

📁 组件库结构

bear-component-library/
├── lib/                  # 构建产物目录
│   ├── index.cjs.js      # CommonJS 格式
│   ├── index.esm.js      # ES Module 格式
│   └── index.d.ts        # TypeScript 类型声明
├── src/                  # 源代码目录
│   ├── components/       # 组件目录
│   │   ├── button/       # 按钮组件
│   │   │   ├── Button.tsx
│   │   │   ├── index.ts
│   │   │   ├── types.ts
│   │   │   └── styles/
│   │   │       └── button.scss
│   │   ├── text/         # 文本组件
│   │   │   ├── Text.tsx
│   │   │   ├── index.ts
│   │   │   ├── types.ts
│   │   │   └── styles/
│   │   │       └── text.scss
│   │   └── index.ts      # 组件导出
│   ├── styles/           # 全局样式
│   │   └── variables.scss
│   └── index.ts          # 主入口
├── package.json          # 包配置
├── rollup.config.js      # Rollup 构建配置
└── tsconfig.json         # TypeScript 配置

❓ 常见问题解答

Q: 为什么组件库同时提供 CJS 和 ESM 格式？

A: 提供两种格式是为了兼容不同的使用场景：

• CommonJS (CJS) 格式适用于 Node.js 环境和旧版构建系统
• ES Modules (ESM) 格式支持树摇（tree-shaking）优化，适用于现代前端构建工具

Q: 如何添加新组件到库中？

A: 按照以下步骤添加新组件：

1. 在 src/components/ 下创建新的组件目录
2. 创建组件文件、类型定义和样式
3. 在组件目录中创建 index.ts 导出组件
4. 在 src/components/index.ts 中添加新组件的导出
5. 重新构建库 (npm run build)

Q: 如何在我的项目中使用自定义主题？

A: 您可以通过以下方式自定义主题：

1. 创建自己的 CSS/SCSS 文件覆盖默认样式
2. 使用组件的 style 属性应用内联样式
3. 使用 CSS-in-JS 库（如 styled-components）包装组件并应用自定义样式

Q: 如何贡献代码到这个项目？

A: 欢迎贡献！请遵循以下步骤：

1. Fork 仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

📦 开发与发布

本地开发

# 安装依赖
npm install

# 启动开发模式（监视文件变化）
npm start

# 构建库
npm run build

# 运行测试（如果已配置）
npm test

本地测试与链接

在发布到npm之前，可以使用npm link在本地测试组件库：

# 在组件库目录中创建全局链接
cd path/to/bear-component-library
npm link

# 在测试项目中使用该链接
cd path/to/your-test-project
npm link bear-component-library

# 现在可以在测试项目中导入组件库了
# import { RedButton } from 'bear-component-library';

# 完成测试后，解除链接
npm unlink bear-component-library
cd path/to/bear-component-library
npm unlink

发布到npm

准备发布到npm之前，需要完成以下步骤：

1. 确保package.json配置正确：

   • 检查name、version、main、module、types和files字段
   • 确保version每次发布前都已更新
   • 验证description、keywords、author和license等元数据

2. 登录npm账号：

   # 登录到npm
   npm login
      
   # 输入用户名、密码和邮箱
   Username: your-username
   Password: your-password
   Email: [email protected]
      
   # 验证登录状态
   npm whoami

3. 发布前测试打包：

   # 清理之前的构建
   rm -rf lib/
      
   # 重新构建
   npm run build
      
   # 检查打包内容
   npm pack
   # 这会创建一个.tgz文件，可以解压检查内容

4. 发布到npm：

   # 发布公开包
   npm publish --access public
      
   # 如果是组织作用域包(@yourorg/package-name)且想设为私有
   # npm publish --access restricted

5. 发布新版本：

   # 更新补丁版本 (1.0.0 -> 1.0.1)
   npm version patch
      
   # 更新次要版本 (1.0.0 -> 1.1.0)
   npm version minor
      
   # 更新主要版本 (1.0.0 -> 2.0.0)
   npm version major
      
   # 然后发布
   npm publish

📄 许可证

MIT © [Open Source Contributor]