BI Components

基于 rslib 的 React 组件库项目，配套接入 Storybook 文档系统与 Biome 代码规范工具；日常开发与构建请使用 pnpm。

技术栈

• React 19 + TypeScript 组件开发
• rslib + rsbuild 负责打包与类型声明产出
• Storybook（storybook-react-rsbuild + storybook-addon-rslib）用于文档与演示
• Ant Design（示例组件引用了 Tag）
• Biome 统一代码格式、语法与样式检查

环境要求

• Node.js v20.19.x（与 .nvmrc 保持一致，可通过 nvm use 快速切换）
• pnpm ≥ 8（项目默认使用 pnpm 锁定依赖）
• 需更新 browserslist 数据库时可执行 npx update-browserslist-db@latest
• 装Biome插件并且配置默认格式化为Biome

安装与快速开始

pnpm install        # 安装依赖
pnpm dev            # 监听模式构建库产物（输出到 dist/）
pnpm storybook      # 启动 Storybook 文档站（默认 http://localhost:6006）
pnpm build          # 生成最终分发产物及类型声明
pnpm build:storybook# 生成静态化 Storybook（输出到 storybook-static/）

pnpm dev 与 pnpm storybook 可同时运行：一个负责构建库文件，另一个负责交互式文档。

新增组件流程

1. 规划结构
   • 在 src/components 下新建组件目录，例如 src/components/Alert/。
   • 建议保持入口文件命名为 index.ts，具体实现放在同目录的业务文件内（如 Alert.tsx）。
   • 类型定义建议放在 types.ts 文件中统一管理。
2. 实现组件
   • 使用 TypeScript 定义 Props，在 types.ts 中导出类型。
   • 若存在样式，放在同目录下的 .css 或 .scss 文件中，并在组件内显式引入。
   • 在组件目录的 index.ts 中按以下模式导出：

     // src/components/Alert/index.ts
     export { default as BiAlert } from './Alert'
     export type { AlertProps } from './types'

   • 在 src/components/index.ts 中添加统一导出：

     export * from './Alert'

   • 主入口 src/index.ts 已通过 export * from './components' 统一导出所有组件。
3. 编写 Storybook 文档
   • 在 stories 目录下新增 Alert.stories.ts（命名与组件保持一致）。
   • 在 meta 中配置分组、参数、控制器，并通过 args 覆盖核心用例。
   • 需要交互事件时使用 fn() 或 action 辅助调试。
4. （可选）补充测试
   • 如果组件逻辑较复杂，推荐在 src/components/Alert/__tests__/Alert.test.tsx 等位置编写单元测试 / 交互测试。
5. 自查与验证
   • 运行 pnpm format、pnpm lint（或 npm run format、npm run lint）保证无格式与 lint 报错。
   • 执行 pnpm dev / pnpm build 确保打包通过。
   • 在 Storybook 中验证组件展示、交互与文档说明是否完整。
6. 提交与评审
   • 保持提交只包含相关改动，附上截图 / 录屏展示关键状态。
   • 在 PR 或合并说明中记录 Storybook 路径、接口变更、兼容性注意事项。

Storybook 使用

• pnpm storybook：本地开发调试组件时实时查看属性变更、文档与交互。
• pnpm build:storybook：打包生成静态文档，输出目录 storybook-static/，可直接部署至静态站点。
• stories 中的命名建议遵循 目录/类别/组件名，以便 Storybook 侧边栏分类清晰。

代码规范与质量检查

• pnpm format：调用 Biome 自动格式化代码。
• pnpm lint：运行 Biome 的 linter 规则（等同于 npm run lint）。
• pnpm check：Biome 综合检查（含 lint + format 建议），适合提交前统一自检。
• 保持组件类型声明完整，避免将外部依赖打包进产物（rslib 默认按需生成类型与 ESM 包）。

导出与使用方式

在业务项目中安装

pnpm add @zw-team/react-lib
# 或
npm install @zw-team/react-lib

请确保业务项目已安装并满足 package.json 中声明的 peerDependencies：react、react-dom、antd、@ant-design/icons、axios、dayjs、zustand（版本需落在各自兼容范围内），否则可能出现重复实例、类型或运行期错误。

按需引入（组件 / Hooks / Utils / Config）

组件库采用多入口 exports，可按子路径按需加载：

• 主入口（@zw-team/react-lib）：导出组件及主题相关（不含 Hooks、Utils，见 src/index.ts）

  import { BiAvatar, BiBlock } from '@zw-team/react-lib'

• 组件入口（@zw-team/react-lib/components）

  import { BiAvatar, BiBlock } from '@zw-team/react-lib/components'

• Hooks 入口（@zw-team/react-lib/hooks）

  import { useLatest, usePermission } from '@zw-team/react-lib/hooks'

• 工具入口（@zw-team/react-lib/utils）

  import { request, ossUpload } from '@zw-team/react-lib/utils'

• 配置入口（@zw-team/react-lib/config）：环境枚举、服务 URL 等（以包内实际导出为准）

  import { EnvType, getServiceURL } from '@zw-team/react-lib/config'

样式与 Sass（使用带 .scss 的组件时必读）

部分组件在产物中仍 import .scss 文件，业务侧打包器必须能解析 Sass。未配置时易出现类似 Module parse failed / Expression expected（把 SCSS 当成 JS 解析）的报错。

• Rsbuild：安装 @rsbuild/plugin-sass 并在配置中注册（参考 npm 说明）。

  import { defineConfig } from '@rsbuild/core'
  import { pluginSass } from '@rsbuild/plugin-sass'
  
  export default defineConfig({
    plugins: [pluginSass()],
  })

• Vite：一般需在项目中安装 sass（常见做法为开发依赖）。
• Webpack：需配置 sass-loader 等以处理 .scss。

组件命名规范

所有组件统一使用 Bi 前缀（如 BiAvatar、BiBlock、BiForm）可在组件的index.ts重新命名加上Bi，便于识别和避免命名冲突。

本地开发与调试

在开发过程中，如果需要在其他项目中实时调试本组件库，可以使用 link 功能将本地开发版本链接到目标项目。

使用 pnpm link

步骤 1：在组件库项目中创建全局链接

# 在本项目根目录执行
pnpm link --global

步骤 2：在目标项目中链接组件库

# 进入需要使用组件库的项目目录
cd /path/to/your-project

# 链接本地组件库
pnpm link @zw-team/react-lib

步骤 3：开启监听模式

在组件库项目中运行监听模式，代码变更会自动编译：

# 在本项目根目录执行
pnpm dev

取消链接（调试完毕）

# 在目标项目中执行
pnpm unlink @zw-team/react-lib

注意事项

• 链接前请确保已执行 pnpm build 至少一次，保证 dist/ 目录存在。
• 使用 pnpm dev 可以监听文件变化并自动编译，方便实时调试。
• 如果目标项目的依赖版本（React、Ant Design 等）与组件库不一致，可能会出现多实例问题，建议保持版本一致。
• 调试完成后记得取消链接，避免影响正常的包管理。

构建与产物

• pnpm build 会在 dist/ 目录生成每个组件的 ESM 代码与 .d.ts 类型文件。
• rslib.config.ts 中配置了多个入口点（index、components、hooks、utils），每个入口都会生成对应的 .js 和 .d.ts 文件。
• bundle: false 配置意味着各入口保持模块化输出，方便 Tree Shaking。
• 发布前请确认 peerDependencies（react / react-dom / antd）版本要求是否符合目标项目。

目录结构（节选）

.
├── .storybook/                 # Storybook 工程配置
├── src/
│   ├── components/             # 组件目录
│   │   ├── Avatar/
│   │   │   ├── Avatar.tsx
│   │   │   ├── index.ts        # 如: export { default as BiAvatar } from './Avatar'
│   │   │   └── types.ts
│   │   ├── Block/
│   │   │   ├── Block.tsx
│   │   │   ├── Block.css
│   │   │   ├── index.ts
│   │   │   └── types.ts
│   │   ├── ...
│   │   └── index.ts            # 组件统一导出
│   ├── hooks/
│   │   ├── useLatest.ts
│   │   ├── usePermission.ts
│   │   └── index.ts
│   ├── utils/
│   │   ├── date.ts
│   │   ├── ossUpload.ts
│   │   ├── request/
│   │   └── index.ts
│   ├── config/
│   │   ├── index.ts            # 环境与服务 URL 等（@zw-team/react-lib/config）
│   │   └── theme/
│   └── index.ts                # 库主入口（组件 + 主题）
├── stories/
├── dist/                       # rslib 构建产物
├── rslib.config.ts
├── biome.json
└── package.json                # exports 多入口

现有组件状态

• 项目已包含多个业务组件，如 Avatar、Block、Form、DatePicker、Dialog、Pagination 等。
• 所有组件统一使用 Bi 前缀命名（如 BiAvatar、BiBlock）。
• 组件均配置了对应的 Storybook 文档，可在开发时查看使用示例。
• 新增组件请遵循现有的目录结构和导出模式，确保文档与测试覆盖。

如需更多约定或流程，可在本仓库新增文档说明，并同步更新此 README。欢迎在问题单或 PR 中提出改进建议。