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

本文总结下近几年维护公司开源 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 自动化等。

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