create-ui-lib

介绍

基于 storybook 扩展的组件库脚手架，用于快速构建 React 组件库。

背景

在前端开发中，我们经常会遇到以下情景：

• 不同的项目在开发相似功能时，要重复写 N 遍；如果团队内部没有可供复用的的组件库，一般会在项目中自己抽离组件，再复制到其他项目：重复劳动，开发效率低，没有沉淀
• 想要自己封装、发布 npm 包，由于缺少统一的规范，导致无从下手或最终呈现的方式不同

目的

• 提高各业务线组件复用率，减少重复开发
• 提供开箱即用的组件库环境，降低开发者上手成本，专注组件开发

特性

• 提供组件开发、构建、发布、文档编写等功能
• 使用 TypeScript 开发，自动生成组件 API
• 完整的目录结构，项目代码组织更规范
• 提供完整的数据请求解决方案

开发组件库需要用什么？

构建一个组件库，需要的工具又广又杂，我们考虑到一个成熟的组件库至少应该满足以下最基本的开发要求：

• 开发环境：基于 storybook开发，让每个组件都有一个独立的开发调试环境。同时提供构建开发文档，一举两得
• 组件库构建：支持生成 esm 和 cjs 模块的组件代码
• 代码格式化和规范检测工具：Eslint + Prettier + Yorkie + Commitlint + Commitizen + Lint-staged 规范前端工程代码规范
• 自动化的文档部署：使用 gitlab-ci 自动部署组件库文档
• 组件单元测试编写：为了组件的稳定性以及减少维护压力，可以使用 Jest + testing-library 进行组件测试

为什么选择 storybook 编写文档？

• ✔︎ 组件库面向的不仅仅是开发者，还有可能是产品、运营、UI 人员

• ✔︎ storybook 创建的文档交互性强，可以在文档中修改参数实时查看效果，便于产品、运营、UI 人员做参考

• ✔︎ 可以为组件自动生成文档和属性列表

快速上手

创建组件库

终端运行以下命令，创建组件库

npx -p create-ui-lib create-library

可根据需要选择是否生成接口请求相关的文件

适配已有项目

终端切到需要改造的项目，执行以下命令

# 终端切到需要改造的项目
cd [projectName]

# 初始化项目
npx -p create-ui-lib create-library --move

请确保需要改造的项目中存在基础文件 package.json

目录结构

├── .storybook
│   ├── mocker                      # 数据mock
│   │   ├── webapi                  # mock文件目录
│   │   ├── index                   # mock数据入口文件
│   │   ├── mockServiceWorker.js    # service worker文件
│   ├── main.js                     # 控制 Storybook 服务器的行为
│   ├── middleware.js               # 接口代理
│   ├── preview.js                  # Storybook 控制渲染
├── dist                            # 构建目录
│   ├── es                          # esm构建结果
│   ├── lib                         # cjs构建结果
├── src
│   ├── components                  # 组件
│   │   ├── story-button            # 示例组件button
│   │   │   ├── demos               # 文档目录
│   │   │   │   ├── xx.stories.mdx  # 组件文档
│   │   │   │   ├── xx.stories.tsx  # 组件示例
│   │   │   │   ├── xx.test.tsx     # 组件测试用例
│   │   │   ├── button.less         # 组件样式文件
│   │   │   ├── button.tsx          # 组件编写文件
│   │   │   ├── index.ts            # 组件入口文件
│   ├── services                    # 接口请求目录
│   ├── index.ts                    # 组件库入口文件
│   ├── Introduction.stories.mdx    # 组件库文档介绍
├── .fatherrc.ts                    # father-build配置文件
├── .gitignore
├── .gitlab-ci.yml                  # 文档自动部署脚本
├── .yarnrc                         # 设置yarn镜像源
├── jest.config.js                  # jest配置文件
├── jest.setup.ts                   # jest配置文件
├── CHANGELOG.md                    # 组件库更新日志
├── package.json
├── README.md
├── tsconfig.json                   # ts配置文件

请根据需要修改 src 下的文件和内容

启动调试

yarn start:docs

# 启动mock数据
yarn mock:docs

添加组件 demo

yarn demo:add

会在 src/components 目录下生成 demo 组件目录

组件打包

yarn build:library

组件发布

组件发布前会先进行打包操作，确保发布最新代码

yarn pub

执行后，会自动将组件发布到 xnpm

组件库发布目录

npm 包包含以下文件

├── dist                            # 构建目录
│   ├── es                          # esm构建结果
│   ├── lib                         # cjs构建结果
├── package.json
├── README.md

升级 create-ui-scripts 核心依赖

yarn upg

运行测试用例

# 运行
yarn test

# watch
yarn test:watch

gitlab 仓库

为方便开发者存放代码，提供了专门的 GitLab Group

创建对应 Project 仓库

仓库创建完成后，和项目进行关联即可

文档部署

将代码 push 到 gitlab 仓库后，会自动部署文档至 gitlab 仓库对应的 pages 地址，查看路径：Seetings - Pages

如果代码没有放在专门提供的 GitLab Group中，请确保当前你的 gitlab 仓库支持 CI/CD。