【组件库封装】：封装一个 Library 什么流程？

1. 前言

在项目开发初期，我们通常会选用主流的UI开发框架来构建应用（例如：基于 React 的 AntDesign、基于 Vue 的 ElementUI）。随着业务研发过程的推进，会逐渐出现在业务角度上有复用价值的自定义组件，如果我们把这些可复用的组件封装为一个一个独立的 Library，并发布到 npm 上，在项目组内共享，可以避免重复造轮子、便于协同开发、提升开发效率。

完整开发一个 Library，会涉及到以下几方面问题：

• 项目托管（Git 或 Svn，建议用 Git）
• JS包管理（npm 或 yarn，建议用 npm）
• 项目结构（monorepo 或 multirepo，个人偏向前者，把相关项目集中在一起存储）
• 开源协议（本文中采用 MIT，愿意咋搞就咋搞）
• 开发语言（建议用 typescript）
• 创建项目
• 项目开发（本文采用 react）
• 代码格式标准化（preitter、editorconfig、eslint、stylelint 等）
• 构建工具（vitejs、babel、webpack、rollup 等）
• 联调（npm link、yarn link）
• 测试（jest）
• 文档（dumi、storybook、gitpages 等）
• 发布（npm publish）

本文将以开源项目 ReactRouter++ 为例，带大家一步步体会这个组件库的完整开发流程。

2. 项目托管

做开源项目，毫无疑问要选择 Git 作为代码管理工具。怎么使用 Git，不再赘述，可以参考下面几篇文章。

• 【Git】：基础的基础
• 【Git】：基础操作篇
• 【Git】：基础协作篇
• 【Git】：Commit规范 + CHANGELOG生成

3. JS包管理

为了方便起见，我建议大多数团队（必须做出许多其他更重要的技术决定）选择最简单的选项 —— npm。它随 node 一起提供，目前能以足够好的方式处理包管理。

4. 项目结构

从目前的开发场景来看，monorepo 更适合我。开源项目 ReactRouter++ 将拆分为 @webj2eedev/react-router-plus-plus 和 @webj2eedev/history-plus-plus 两个子项目。这两个子项目都将由我一个人研发，monorepo 结构可以让我避免在两个仓库间反复切换，简化开发流程。

5. 开源协议

什么是许可，当你为你的产品签发许可，你是在出让自己的权利，不过，你仍然拥有版权和专利（如果申请了的话），许可的目的是，向使用你产品的人提供 一定的权限。

不管产品是免费向公众分发，还是出售，制定一份许可协议非常有用，否则，对于前者，你相当于放弃了自己所有的权利，任何人都没有义务表明你的原始作 者身份，对于后者，你将不得不花费比开发更多的精力用来逐个处理用户的授权问题。

而开源许可协议使这些事情变得简单，开发者很容易向一个项目贡献自己的代码，它还可以保护你原始作者的身份，使你至少获得认可，开源许可协议还可以阻止其它人将某个产品据为己有。

6. 开发语言

不需要多说，TypeScript 可以极大地增加前端代码的可维护性。必然是要选 TypeScript 作为基础开发语言。

• 枚举
• 接口
• 泛型
• 类
  • private
  • public
• 重载
• 继承
• ......

7. 创建项目（创建以 @ 开头的共有包）

As an organization member, you can create and publish public and private packages within the organization's scope.

• 在 npm 官网中创建 Organization；

• Create an organization scoped package：

npm init --scope=<your_org_name>

• Publish an organization scoped package as public

npm publish --access public

8. 开发

本文着重讲解一个 library 库的整体研发路线，不深入组件开发细节。基于 Typescript、React、React Hooks 技术，完成 @webj2eedev/history-plus-plus、@webj2eedev/react-router-plus-plus 项目的研发

9. 代码格式标准化

9.1. EditorConfig

• EditorConfig 是什么？
  • EditorConfig helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs.
• 配置 .editorconfig
  • 基于开源项目 Redux 中的 .editorconfig 配置，稍微做了一点调整

• 安装 EditorConfig VSCode 插件
  • WebStorm 默认支持 .editorconfig，但是 VSCode 需要通过安装插件实现支持

9.2. Prettier

• Prettier 是什么？
  • Prettier enforces a consistent code style (i.e. code formatting that won’t affect the AST) across your entire codebase because it disregards the original styling* by parsing it away and re-printing the parsed AST with its own rules that take the maximum line length into account, wrapping code when necessary.
• 配置 .prettierrc
  • 使用的是开源项目 vue-router 中的 .prettierrc 配置

• 安装 Prettier VSCode 插件

• 调整 VSCode 默认格式化工具为 Prettier

9.3. ESLint

• ESLint 是什么？
  • ESLint is a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code, with the goal of making code more consistent and avoiding bugs. In many ways, it is similar to JSLint and JSHint with a few exceptions:
    • ESLint uses Espree for JavaScript parsing.
    • ESLint uses an AST to evaluate patterns in code.
    • ESLint is completely pluggable, every single rule is a plugin and you can add more at runtime.
• 安装 ESLint VSCode 插件

• 初始化 ESLint 配置

npx eslint --init

• 按需调整 ESLint 配置

10. 构建工具

目前的主流 Web 构建工具主要包含：webpack、vitejs、rollup、glup、parcel 等。本文选择目前社区中比较火爆的“下一代前端构建工具 ViteJS”作为我们项目的构建工具。

• Vitejs 是什么？
  • Vite 是一个由原生 ESM 驱动的 Web 开发构建工具。在开发环境下基于浏览器原生 ES imports 开发，在生产环境下基于 Rollup 打包。
• Vitejs 关键特性？
  • 快速的冷启动
  • 即时的模块热更新
  • 真正的按需编译
  • 默认支持 TypeScript，开箱即用
  • 默认支持 jsx、tsx，开箱即用
  • 支持 HMR
• Vitejs 初始配置？

11. 联调

npm link 在测试阶段，可应用于在父子项目之间建立软连接，避免反复往 npm 仓库中发包。

This is handy for installing your own stuff, so that you can work on it and test iteratively without having to continually rebuild. https://docs.npmjs.com/cli/v7/commands/npm-link

例如：A 项目依赖 B 项目

• 第一步：在 B 项目中，执行 npm link

npm link

• 第二步：在 A 项目中，执行 npm link B

npm link B

12. 测试

靠谱的开源软件必然是需要单元测试的，这是软件在持续迭代的过程中保持稳定的非常必要的手段。

• React 体系下，选用 Jest 测试框架，配合 @testing-library，就足够了。

• 在 VSCode 中安装 Jest 插件，会提升测试的便捷性。

• 基于 Jest 测试框架编写测试用例

12. 文档

靠谱的开源软件必然需要靠谱的文档，vuepress、dumi、storybook 都是优秀的基于 Markdown 的快速建站工具。这些工具不仅能编写文档，还可以在线展示可运行的代码示例。

13. 发布

• 完善 package.json 中用于描述项目的信息：
  • author、contributors：The "author" is one person. "contributors" is an array of people.
  • bugs：The url to your project's issue tracker and / or the email address to which issues should be reported.
  • description：Put a description in it. It's a string.
  • homepage：The url to the project homepage.
  • keywords：Put keywords in it. It's an array of strings.
  • license：You should specify a license for your package so that people know how they are permitted to use it, and any restrictions you're placing on it.
  • repository：Specify the place where your code lives.

• 完善 package.json 中与软件包导出相关的信息
  • files：The optional files field is an array of file patterns that describes the entries to be included when your package is installed as a dependency.
  • main：The main field is a module ID that is the primary entry point to your program.
  • browser：If your module is meant to be used client-side the browser field should be used instead of the main field.
  • module：pkg.module will point to a module that has ES2015 module syntax

• 使用 npm publish 命令发布软件包
  • 注意：这是一个在 Organization 下的 public 类型项目，需要配合 --access public 参数使用

npm publish --access public

参考：

Creating and publishing an organization scoped package： https://docs.npmjs.com/creating-and-publishing-an-organization-scoped-package editorconfig： https://editorconfig.org/ Prettier： https://prettier.io/ ESLint： https://eslint.org/ Vitejs： https://vitejs.dev/ https://github.com/vitejs/vite/tree/main/packages/create-app/template-react-ts