--- theme: channing-cyan highlight: a11y-dark --- ## 前言本篇来讲讲组件库的搭建过程，并搭建一个简单模板集成到上篇的[工欲善其事必先利其器（制作CLI）](https://juejin.cn/post/7214318587431059514)中 ## 环境准备为了方便测试最好先准备本地私仓，私仓搭建可以参考我的这篇：[Docker 部署npm私仓 Verdaccio](https://juejin.cn/post/7139866727831044109) ## Monorepo 什么是 **Mono-Repo**？一言以蔽之：**Mono-Repo** 就是一仓多项目。与之对应的是 **Multi-Repo**：一仓一项目。他们的区别可以参考 Markus Oberlehner 的 [Monorepos in the Wild](https://medium.com/@maoberlehner/monorepos-in-the-wild-33c6eb246cb9) **Mono-Repo** 的好处，简单讲，可以统一流程、规范，简化模块间相互引用等 ### workspaces 选择结合 [lerna](https://lerna.js.org/) 来管理 `workspaces` 也可以，但是 `lerna` 已不再维护，且其体验也不是很好现在`npm`、`yarn`、`pnpm` 都有自己对应的 `workspaces` 方案，参考文档 [npm workspaces](https://docs.npmjs.com/cli/v9/using-npm/workspaces)、[yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/)、[pnpm workspaces](https://pnpm.io/zh/workspaces) 这里选择 `pnpm`，原因有两点： - [平铺的结构不是 node_modules 的唯一实现方式](https://pnpm.io/zh/blog/2020/05/27/flat-node-modules-is-not-the-only-way) - `pnpm` 天生支持 `Monorepo` 也就是 `workspace` 特性，比其他方案要更简便 ### npm organizations 一些库的名称有@your_org_name/ 结构，如 ```json "devDependencies": { "@typescript-eslint/eslint-plugin": "^5.57.0", "@typescript-eslint/parser": "^5.57.0" } ``` 想要这种结构的，需要先在 npm 上创建自己的组织 #### 创建组织 1. 登录[npm 官网](https://www.npmjs.com/) 1. 点击个人头像选择添加组织 ![screenshot-20230406-173930.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/38ad8d7c253a4f11ae0cd963c2f97c04~tplv-k3u1fbpfcp-watermark.image?) 1. 根据提示完成组织创建 ![screenshot-20230406-174118.png](https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/abcd315e52dd448faa612f21a02b355a~tplv-k3u1fbpfcp-watermark.image?) #### 使用 1. cd 到对应项目 package.json 目录下 2. 登录 npm 3. 执行 `npm init --scope=`，如 `npm init --scope=@moloch` 4. 根据提示输入即可 ### tsconfig.json 然后需要增加 `tsconfig.json`的 `paths` 配置，如 ```json "paths": { "@moloch/*": ["packages/*"] } ``` ## Release工作流在 **Multi-Repo** 中，Release工作流大致如下 1. 进行开发 2. 提交变更集 3. 提升版本 4. 发包而在 **Mono-Repo** 中对包版本管理是一个非常复杂的工作，我们以一个小例子来体验下 ### 例子初始化一个项目，目录结构如下 ```md ├─.npmrc ├─package.json ├─pnpm-workspace.yaml ├─tsconfig.json ├─packages | ├─utils | | ├─index.ts | | └package.json | ├─components | | ├─Button.tsx | | ├─index.ts | | └package.json ``` - .npmrc，设置私有源，根据自己私仓实际部署进行配置 ``` registry=http://127.0.0.1/ ``` - pnpm-workspace.yaml 配置 `pnpm-workspace` 目录 ``` packages: - 'packages/**' ``` - package.json，配置以下内容，`private：true`的意思是当前目录标记为私有，禁止发布，因为这里的包只有 `packages` 里的 `components` 和 `utils` ```json { "private": true, "workspaces": [ "packages/*" ], } ``` - `components` 和 `utils` 的包命名，假设都属于 `@m` 这个组织的 ```shell # cd 至 components 目录下执行以下命令 npm init --scope=@m # cd 至 utils 目录下执行以下命令 npm init --scope=@m ``` - 安装 `vue`，`components` 和 `utils` 都用到，`--filter` 是指定哪个子项目安装 ```shell pnpm i vue -D --filter utils pnpm i vue -D --filter components ``` 还可以指定匹配的包进行相应操作 ```shell # 构建 packages 下所有包 pnpm build --filter "./packages/**" ``` - utils/index.ts ```javascript import type { App, Plugin } from 'vue' export type SFCWithInstall = T & Plugin export const withInstall = (component: T, alias?: string): SFCWithInstall => { const comp = component as SFCWithInstall comp.install = (app: App): void => { if (comp.name) { app.component(comp.name, comp) } if (alias) { app.config.globalProperties[alias] = component } } return component as SFCWithInstall } ``` - Button.tsx ```javascript import { withInstall } from '@m/utils' import { defineComponent } from 'vue' const Button = defineComponent({ name: 'Button', setup() { return (): JSX.Element => { return

Button.tsx

} } }) export const _Button = withInstall(Button) export default _Button ``` 这里引用了 `@m/utils` 的内容，需要安装 `@m/utils`模块 ```shell pnpm i @m/utils -r --filter @m/components ``` 此时 `components/package.json` 增加了 `@m/utils` ```json "dependencies": { "@m/utils": "workspace:^" } ``` 分别到 `components` 和 `utils` 目录下执行 `pnpm publish` 发布命令，私仓上可以看到对应包已经发布成功了 ![20230407-153227.jpg](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/5d1b1ce29b6c449da1fb83650e4f6740~tplv-k3u1fbpfcp-watermark.image?) 手动发布，每次都需要人为进行繁琐操作，很容易出错，有没有比较方便的版本控制工具呢？ `pnpm` [推荐](https://pnpm.io/zh/workspaces#%E5%8F%91%E5%B8%83%E5%B7%A5%E4%BD%9C%E6%B5%81)了两个开源工具： - [changesets](https://github.com/changesets/changesets) - [Rush](https://rushjs.io/) ### changesets 以 [changesets](https://github.com/changesets/changesets) （文档比较清晰）为例 - 安装 ```shell pnpm add -wD @changesets/cli ``` - 初始化 ```shell pnpm changeset init ``` - 配置 ```json { "$schema": "https://unpkg.com/@changesets/config@2.3.0/schema.json", "changelog": "@changesets/cli/changelog", "commit": true, "linked": [["@m/*"]], "access": "restricted", "baseBranch": "main", "updateInternalDependencies": "patch", "ignore": [] } ``` 配置说明： - changelog： changelog 生成方式，也可用 github 格式，附带 commit link，如 ```json "changelog": ["@changesets/changelog-github", { "repo": "changesets/changesets" }] ``` - commit：changeset 在 publish 的时候自动 git add - linked：配置哪些包要共享版本 - access：公有私有安全设定，内网建议 restricted ，开源使用 public - baseBranch：项目主分支 - ignore：不需要变动 version 的包 - updateInternalDependencies：确保某包依赖的包发生 upgrade，该包也要发生 version upgrade 的衡量单位（量级）更详细说明请参考[changesets config Documentation](https://github.com/changesets/changesets/blob/main/docs/config-file-options.md) #### 配置 changeset 脚本 ```json "scripts": { "pub": "pnpm changeset & pnpm version-packages & pnpm release", "changeset": "changeset", "version-packages": "changeset version", "release": "changeset publish", }, ``` - `changeset`命令，开始交互式收集变更集，这个命令会列出全部的包给你选择要更改发布的包 - `changeset version`命令，修改需要发布的包的版本，默认提供[semver 规范](https://semver.org/)的选择，分别是 `patch`、`minor` 和 `major` - `changeset publish`命令, 发布版本变化了的包 - 最后由 `pub` 脚本来统一调用 #### prereleases 模式有时我们不想发布 **release** 版本，可以使用 [prereleases 模式](https://github.com/changesets/changesets/blob/main/docs/prereleases.md) ，通过`pnpm changeset pre enter ` 命令进入 pre 模式，操作完后，通过 `pnpm changeset pre exit` 命令退出该模式 tag 一般有如下几种： | 名称 | 功能 | | --- | --- | | alpha | 内部测试版，一般不向外部发布，会有很多Bug，只有测试人员使用 | | beta | 也是测试版，这个阶段的版本会一直加入新的功能。在Alpha版之后推出 | | rc | 发行候选版，这个版本不会再加入新的功能了，主要着重于除错 | 为方便我们写个简单的脚本，新建 `scripts` 文件夹，在该文件夹下新建 `select-pre.sh` 脚本文件，并写入以下内容 ```sh #!/bin/sh PS3='Please enter your choice: ' options=("alpha" "beta" "rc" "Quit") pre='' select opt in "${options[@]}" do case $opt in "alpha") echo "you chose alpha" pre='alpha' pnpm changeset pre enter alpha break ;; "beta") echo "you chose beta" pre='beta' pnpm changeset pre enter beta break ;; "rc") echo "you chose rc" pre='rc' pnpm changeset pre enter rc break ;; "Quit") pnpm changeset pre exit break ;; *) echo invalid option;; esac done # 提交变更集 pnpm changeset # 选择版本 pnpm version-packages # 发包 pnpm release if $pre != '' ; then pnpm changeset pre exit fi echo "✅ Publish completed" ``` `package.json` 更改 `pub` 脚本命令为 `pnpm scripts/select-pre.sh` ```json "scripts": { "preinstall": "npx only-allow pnpm", "pub": "pnpm scripts/select-pre.sh", "changeset": "changeset", "version-packages": "changeset version", "release": "changeset publish" }, ``` 再次执行 `pnpm pub`，就可以根据选择进行对应发版流程了，而且每次发版会把收集到的版本日志写入在对应包里的 `CHANGELOG.md` 通过`changesets`我们了解了 **Mono-Repo** 项目的 Release 工作流，当然 `changesets` 方案并不能满足所有场景需要，不同项目想要更好的体验需要自定义 Release 工作流 ### 自定义 Release 工作流要想根据不同情况针对性处理就需要自定义一套解决机制了，一部分开源项目就是根据具体情况自己实现一套管理机制，如：[vue3](https://github.com/vuejs/core)、[vite](https://github.com/vitejs/vite)、[element-plus](https://github.com/element-plus/element-plus) 等等 #### element-plus 自定义 Release 工作流从 [element-plus](https://github.com/element-plus/element-plus) 来看自定义 Release 工作流首先 [element-plus packages](https://github.com/element-plus/element-plus/tree/dev/packages) 有如下包 ```md ├─packages | ├─utils | ├─components | ├─constants | ├─directives | ├─hooks | ├─locale | ├─test-utils | ├─theme-chalk | ├─element-plus ``` 但是我们使用的时候只关注 [element-plus](https://www.npmjs.com/package/element-plus) 这个主包，这是因为经过打包，其他内容（包括样式[theme-chalk](https://www.npmjs.com/package/@element-plus/theme-chalk)）都打包进 [element-plus](https://www.npmjs.com/package/element-plus) 进行统一发布了除了 `packages` ，在 [element-plus internal](https://github.com/element-plus/element-plus/tree/dev/internal) 也还有一些插件包在 [发布脚本 publish.sh](https://github.com/element-plus/element-plus/blob/dev/scripts/publish.sh) 中可以看到其 Release 工作流 ```sh #!/bin/sh set -e pnpm i --frozen-lockfile pnpm update:version pnpm build cd dist/element-plus npm publish cd - cd internal/eslint-config npm publish cd - cd internal/metadata pnpm build npm publish cd - echo "✅ Publish completed" ``` 这个流程实际上和`changesets`有一些区别，就是装依赖 -> 更新版本 -> 打包 -> 发布核心包，其中执行 `pnpm build` 之后会把内容都集中打包到 `dist/element-plus` 文件夹下，然后再进入该文件夹进行发布从这可以看出 **Mono-Repo** Release 工作流可以理解为是基于 **Multi-Repo** Release 工作流的拓展，因为无论 **Mono-Repo** 多复杂，每个单包的流程大体是不变的，**Mono-Repo** 更多的是在复杂项目中提供更好的组织方式 ## 完善现在我们知道一个组件库在大的方向上要考虑2点： - 项目组织方式 - 确定 Release 工作流这两个方向确定了之后，就可以制定统一的规范，或者拓展流程了 ### 统一代码规范可参考 [工欲善其事必先利其器（前端代码规范）](https://juejin.cn/post/7193258299939586085) 这里补充一点，我们的发布脚本设置了自动 `commit` 一条 `release` 记录 ```sh # commit git add -A git commit -m "release: $VERSION" ``` 所以 `commitlint.config.js` 需要增加 `release` 规则 ```js const typesConfig = require('cz-conventional-changelog-zh/src/types.json'); module.exports = { extends: ['@commitlint/config-conventional'], rules: { 'type-enum': [2, 'always', ['release', ...Object.keys(typesConfig)]] } } ``` ### 打包一些简单的库或许不需要打包，直接发布源码也是可以的，比如在[工欲善其事必先利其器（制作CLI）](https://juejin.cn/post/7214318587431059514)篇中实现的`CLI`：[moloch-create](https://github.com/moloch-z/moloch-create) #### 模块化规范打包需要考虑输出符合各种 `模块化` 规范（AMD, CMD, CommonJS，UMD等）的文件，如果需要支持 `typescript` 还需要处理 `.d.ts` 声明文件我们以 [rollup](https://www.rollupjs.com/) 为打包工具，写一个简单的打包流程，新建公共打包入口 `build/build.ts`，为了方便，这里仅处理两种规范 ```javascript import glob from 'fast-glob' import { rollup } from 'rollup' import esbuild from 'rollup-plugin-esbuild' import vueJsx from '@vitejs/plugin-vue-jsx' import { nodeResolve } from '@rollup/plugin-node-resolve' export async function build() { const modulePath = process.cwd() const files = await glob('*.{ts,tsx}', { cwd: modulePath, absolute: true, onlyFiles: true }) const excludes = ['node_modules'] const input = files.filter(path => !excludes.some(exclude => path.includes(exclude))) const reg = /\\([^\\]+)$/ modulePath.match(reg) const packageJson = await import(`../packages/${RegExp.$1}/package.json`, { assert: { type: 'json' } }) const { dependencies = {} } = packageJson const bundle = await rollup({ input, plugins: [ nodeResolve({ extensions: ['.ts', '.tsx'] }), vueJsx(), esbuild({ sourceMap: true, target: 'esnext' }) ], external: Object.keys(dependencies), treeshake: true }) const configs = [ { format: 'cjs', ext: 'js' }, { format: 'esm', ext: 'mjs' } ] as const configs.forEach(config => { bundle.write({ format: config.format, exports: config.format === 'cjs' ? 'named' : undefined, dir: `${modulePath}/lib`,//指定输出到模块下lib文件夹 preserveModules: false, sourcemap: true, entryFileNames: `[name].${config.ext}` }) }) } build() ``` 由于 `node` 默认是 `Commonjs` 规范，这里安装 `ts-node` 来执行 `build.ts` ```sh pnpm i -wD ts-node @types/node ``` `package.json` 增加以下配置，`"type": "module"`表示以`ESM`模块运行，`scripts` 配置打包命令 ```json "type": "module", "scripts": { "build": "pnpm --filter=@m/* run build", } ``` `packages/components/package.json` 增加以下配置 ```json "files": [ "lib" ], "scripts": { "build": "node --loader ts-node/esm ../../build/build.ts" }, "exports": { ".": { "require": "./lib/index.js", "import": "./lib/index.mjs" } }, ``` `files`指定发布内容，因为打包指定输出目录为`lib`，这里设置为`lib`，`exports` 指定不同规范引用的文件 `select-pre.sh` 增加打包步骤 ```sh # 打包 pnpm build # 提交变更集 pnpm changeset # 选择版本 pnpm version-packages # 发包 pnpm release ``` 提交代码，再次执行 `pnpm pub`发布一个版本 ![screenshot-20230413-141134.png](https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/acf30f8c469b456da5ba08dd46305491~tplv-k3u1fbpfcp-watermark.image?) 当然每个模块下都可以有自己的`README.md`，比如`components` 增加`README.md` 使用方式 - Installation ```sh $ pnpm i --save @m/components ``` - Usage ```ts ``` `@m/utils`也是类似的处理，这里就不再细说另外像`@m/components`、`@m/utils`这些包就应该合在一个包里方便使用，可以参考 [element-plus](https://www.npmjs.com/package/element-plus) 把 **Mono-Repo** 的多个项目打包到一个项目下统一发布 #### 打包链路 **Mono-Repo** 项目涉及到打包链路的可能还需要**依赖拓扑链路解决方案：[turborepo](https://github.com/vercel/turborepo)**，可参看 [Turborepo Documentation](https://turborepo.org/docs) ### 流程守护在上文的例子中，`发布`前都没有做任何校验，如果误操作很有可能就把还不该发布的代码发布上去了，为了不出现这种情况，就需要增加流程守护 - 在 `代码规范` 里有规范守护，`测试` 也可以纳入了提交流程 - 发布前可以增加 `git-release` 流程，比如[element-ui](https://github.com/ElemeFE/element)就有 [git-release.sh](https://github.com/ElemeFE/element/blob/dev/build/git-release.sh)脚本检查分支是否**干净** 如果每个版本都想要更好的追踪源码，也可以参考[element-ui](https://github.com/ElemeFE/element)在[release.sh](https://github.com/ElemeFE/element/blob/dev/build/release.sh)脚本里增加打上 `tag` 并在发布后自动推送的操作 ### 文档简单的库只需要在 `README.md` 编写使用文档即可一些类库如果严格要求书写 `JSDoc` 的可以利用 `JSDoc` 生成文档；如 `ts-morph` 可以分析 `TypeScript` 中的 `JSDoc`，最终生成包含函数名、描述和参数信息的 `Markdown` 或 `HTML` 文档复杂的组件库文档方案可以考虑 [vuepress](https://vuepress.vuejs.org/)、[vitepress](https://vitejs.cn/vitepress/)、[storybook](https://storybook.js.org)，因为文档都比较齐全，这里就不详细介绍了 #### 变更日志完善的文档还需要有变更日志，在[工欲善其事必先利其器（前端代码规范）](https://juejin.cn/post/7193258299939586085)已经规范了提交信息，现在只需要利用起来即可整个 [conventional-changelog 生态](https://github.com/conventional-changelog) 有很多，这里只需补充 [conventional-changelog-cli](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-cli) 即可 `conventional-changelog-cli` 可以从`git metadata` 生成变更日志 - 安装 conventional-changelog-cli ```sh pnpm i -wD conventional-changelog-cli ``` - 基本使用，全局安装可以不需要 `pnpm` ```sh pnpm conventional-changelog -p angular -i CHANGELOG.md -s ``` 以上命令中参数 `-p angular` 用来指定 `angular` 的 `commit message` 标准，使用 `atom` 标准只需把 `angular` 改为 `atom` 参数`-i CHANGELOG.md` 表示从 `CHANGELOG.md` 读取 `changelog`, `-s` 表示读写 `changelog` 为同一个文件。另外这条命令产生的 `changelog` 是基于上次 `tag` 版本之后的变更（Feature、Fix、Breaking Changes等）所产生的一般项目初始化或者你想生成之前所有 `commit` 信息产生的 `changelog` 则需要使用这条命令： ```sh pnpm conventional-changelog -p angular -i CHANGELOG.md -s -r 0 ``` 其中 `-r` 表示生成 `changelog` 所需要使用的 `release` 版本数量，默认为 1，全部则是 0。 #### 集成到 Release 工作流中在 `package.json` 增加 `changelog` 的 `scripts`， ```json "scripts": { "changelog": "pnpm conventional-changelog -p angular -i CHANGELOG.md -s -r 0" }, ``` 最后增加 `publish.sh` 脚本中 ```sh # 更新版本 TAG_VERSION=$VERSION pnpm update:version # changelog pnpm changelog ``` ## 其他 **Mono-Repo** 项目或许会非常复杂，像[element-ui](https://github.com/ElemeFE/element) 新建一个组件需要改动多个地方，为了减少出错，`element-ui` 提供 `make new` 命令执行 [new.js](https://github.com/ElemeFE/element/blob/dev/build/bin/new.js) 脚本创建组件，`new.js` 脚本会自动处理相关的文件;其他 `make` 命令可参考 [Makefile](https://github.com/ElemeFE/element/blob/dev/Makefile) ## 总结本篇简单讲解了组件库搭建过程需要了解的一些点，最核心的就是确定 **项目组织方式** 和 **Release 工作流**，剩下的就是根据项目的实际情况进行调整，本文例子 [github: lib-template](https://github.com/moloch-z/lib-template) ## 相关文章 [Monorepo基于gulp+rollup打包简析](https://juejin.cn/post/7225161813704097847) ## 系列文章 - [工欲善其事必先利其器（前端代码规范）](https://juejin.cn/post/7193258299939586085 "https://juejin.cn/post/7193258299939586085") - [工欲善其事必先利其器（配置Vue3 + ts项目模板）](https://juejin.cn/post/7200930164821000229 "https://juejin.cn/post/7200930164821000229") - [工欲善其事必先利其器（制作CLI）](https://juejin.cn/post/7214318587431059514 "https://juejin.cn/post/7214318587431059514") - [工欲善其事必先利其器（搭建组件库）](https://juejin.cn/post/7221409486697709629 "https://juejin.cn/post/7221409486697709629") - [工欲善其事必先利其器（css多主题）](https://juejin.cn/post/7244352006814367804 "https://juejin.cn/post/7244352006814367804") - [工欲善其事必先利其器（测试）](https://juejin.cn/spost/7253476306007752759)