cover
2022年8月16日 - 2023年7月31日

写个开源组件库需要知道些什么

本文总结下近几年维护公司开源 React 组件库的一些经验。文章主要分为六部分讲解:

  • 组件编写
  • 文档
  • 构建/发包
  • 开源
  • 测试
  • 其它

本文制作概念阐述,不做实操讲述,后面会分几篇分别介绍每个部分。

组件编写

这部分主要分为组件技术选型和编写组件时注意要点。

技术选型

技术选型主要包括三部分:样式编写选型、JS 编写选型,这两方面主要要看团队技术栈和发展来决定。

由于组件编写样式需要非常重视隔离的问题,否则很容易在各种环境下由于各种样式覆盖导致一场。

常用的样式编写有以下几种方案:

  • css in js
  • css modules
  • BEM 命名
  • shadow DOM

每个方案间各有优劣,最好视团队目前情况后后续发展来决定,不建议混合方案。

JS 编写选型主要是编写时所用的语言,可以使用:

  • js
  • ts
  • flow
  • coffeescript 等

此处如果团队有能力建议直接使用 TS,对于组件而言接口类型和代码质量都很重要,使用 TS 可以对这两方面有显著提升。当然 flow 等也有这方面的优势,不过鉴于发展趋势,TS 无疑是最佳选择。

编写规范

对于公共组件而言,最重要的不是性能、不是质量、不是体积,而是组件的 API 定义。API 一旦定义好,组件的使用风格就会逐渐定型,后期的改动很难去改动已有 API 的定义,还有 API 风格的统一也有助于降低使用者的学习成本。

这就需要在早期就定义好 API 规范,比如:

  • 受控非受控的 API 名称:value、defaultValue、checked、defaultChecked
  • 回调的名称:onChange、onClick、onSelect
  • 透传 props:partProps
  • 控件风格、尺寸、类型等

要注意 API 的可读性、可理解性、是否符合直觉等,可以在早期慢慢定义,参考各类开源库,编写时逐步补充。

并且在早期不建议开放太多的接口,接口一旦开放,后期的升级维护就势必需要考虑,有时会无端增加维护成本。

除了 API 规范后,编写时另外的几个要点:

  • 性能
  • 代码质量
  • 代码复用

针对性能可以定义一些简单的指标,比如保障 Select 组件 1000 条数据无卡顿等。

代码质量这个比较虚,需要借助其它工具来进行检测,后面会讲到。

代码复用在 React 中则有多种方式,如组件颗粒化复用、早期的 mixin、HOC 抽离、decorator,还有大火的 hooks。

除此之外还需要注意组件结构,比如子组件结构,常见的有命名结构:Button、ButtonGroup;或是组件属性挂载,如 Button、Button.Group。

文档

组件除了编写方面的问题,第二重要的便是文档,有了文档才能让开发者方便的使用组件,展示组件的功能。开源常见的与文档相关的工具主要为:storybook 和 react-styleguidist。可以直接读取组件中的 API 定义,生成文档。

当然也可以选择常见的文档系统,然后人工维护,或者自研。

注意明确文档的功能,来选择方案,比如文档需要有哪些功能,常见的包括:组件的文档描述、功能介绍、props、method 定义、demo 演示等。选择时还需要考虑文档的编写成本,如是否可以直接读取注释、组件定义、是否需要额外维护。此外 react-styleguidist 支持实时编辑预览 demo,storybook 支持直接使用 controls 预览 props 变更效果等也可以作为选择时的依据。

构建/发包

组件构建工具选择不是很重要,可以自行选择 webpack、rollup 等,主要要注意的是兼容、输出格式等方面。

比如需要决定好组件针对的的目标环境,针对环境可能需要去配置 browserlist、babel、post-css 来兼容,还需要做好兼容测试。

打包是还需要注意输出的格式:esm、cjs、umd 等,同时要输出 sourcemap、接口定义等,这样才能方便开发者调试和反馈问题。

打包完成后便是发包,正常会法包至 npm,需要注意好发布的文件、版本号规范、依赖项、协议、tree-shaking、模块文件定义等等,这个可以翻一翻 package.json 中的字段定义。

开源

开源时需要选择托管平台,比如 github、gitlab、gitee 等,可以 GitHub + gitee 来避免某些不可说的访问失败。

同时开源后可以利用好托管平台的功能,如在 github 中可以使用:issue、pr、pages、action、编写 contribution guide 等。

还有需要注意选择开源协议,常规开源项目大部分为 MIT 协议。

测试

为了组件的稳定性,还需要做好测试,测试可以分为两类:方法测试和 UI 测试。

方法测试很简单,针对方法写好单测即可,UI 测试一般需要选择相应的测试库,进行 UI 单元测试,比如测试 disabled 下的 button 组件是否会触发 onClick、测试 select 点击后是否能够正常弹出等。

测试生态中常用的包含一下库:

  • jest
  • enzyme
  • react-testing-library
  • @testing-library

除此外还可进行快照测试,一般的快照测试为直接保存渲染的 DOM 结构的快照,在测试时和已有的快照进行比对,让开发者知道更新后的 DOM 改动。

除了快照测试外,还有图片/像素测试,常见的如:jest-image-snapshot、jsdom-screenshot 等,可将获取组件渲染截图,然后对比设计稿进行像素级比对,也可保存报告结果,比对改动前后的差异。不过需要注意保存图片会占用很多空间,很容易导致 git 资源过多影响平时的同步,所以一般很少会使用。

除了上述具体测试方法外还有测试的覆盖率,覆盖率为测试代码执行时源码中的执行比例,可通过覆盖率来粗略判断测试逻辑是否完善,是否有逻辑遗漏。

其它

除了上述常用内容外,还可以借助很多其它工具来完善组件,如:

  • eslint - 用来规范代码编写,检查代码质量
  • prettier - 用于规范代码格式,统一代码风格
  • stylelint - 检查样式规范和简单的错误
  • commitizen - 规范代码提交,自动化生成 changelog
  • husky,lint-staged - 通过 githook 自动化完成代码格式化、lint 检查
  • ci/cd - 借助 GitHub action、gitlab ci、circle ci、travis 等通过自动化方式进行代码测试、打包、发包、文档生产、部署等等

除此外还需要注意开源时的贡献规范、issue 治理等。

总结

其实相关的内容不只是针对开源 React 组件库,在平时的开发中很多内容也可以用的上,比如规范团队风格、CI/CD 自动化等。

以上便是我总结的关于组件开发中的一些注意事项、生态、经验等,后续会为每个部分出一篇详细的文章,有兴趣的同学可以关注下。