Lerna 最佳实践(内含大量代码)
在介绍本文的主角 lerna 之前,首先了解下什么是 multirepo ?什么是 monorepo ?
multirepo 指的是将模块分为多个仓库,monorepo 指的是将多个模块放在一个仓库中。
multirepo 可以让每个团队都拥有自己的仓库,他们可以使用自己的构建流程、代码规范等,但是同时也会存在很多问题,比如模块之间如果存在相互依赖,就必须到目标仓库里进行 bug 修复、构建、发版本等,相互依赖关系越复杂,处理起来就越困难。
monorepo 可以让多个模块共享同一个仓库,因此他们可以共享同一套构建流程、代码规范也可以做到统一,特别是如果存在模块间的相互依赖的情况,查看代码、修改 bug、调试等会更加方便,因此也越来越受到大家的关注,像 Babel、React、Vue 等主流的开源仓库都采用的 monorepo。
lerna
lerna 是一个管理工具,用于管理包含多个软件包(package)的 JavaScript 项目,最早是 Babel 自己用来维护自己的 monorepo 并开源出的一个项目,针对使用 git 和 npm 管理多软件包代码仓库的工作流程进行优化,解决多个包互相依赖,且发布需要手动维护多个包的问题。
总结一下,使用 lerna 可以帮我们解决如下几个痛点:
多个仓库之间可以管理管理公共的依赖包,或者单独管理各自的依赖包
方便模块之间的相互引用,模块之间的调试不必发版本,lerna 内部会自动进行 link
lerna 提供了两种模式,支持选择单独针对某个包发版本或者统一发版本
多个仓库之间可以共享统一的代码规范,版本管理更加规范
以下会分两个部分介绍,首先是介绍 lerna 的常规用法,然后介绍下 lerna 的最佳实践。
基本用法
安装
$ npm install --global lerna
创建一个 git 仓库
$ git init lerna-repo && cd lerna-repo
初始化一个 lerna 仓库
$ lerna init
注意,lerna init 可以通过参数 --independent 进入 Independent 模式,该模式可以单独发版本。
初始化之后的工程目录结构如下:
lerna-repo├── lerna.json├── package.json└── packageslerna.json:{"packages": ["packages/*"],"version": "0.0.0"}package.json:{"name": "root","private": true,"devDependencies": {"lerna": "^4.0.0"}}
新增 package 包
使用 lerna create 创建两个包 pkg1 和 pkg2
lerna create pkg2
创建完成后的目录结构如下:
lerna-demo├── README.md├── lerna.json├── package.json└── packages├── pkg1│ ├── README.md│ ├── tests│ ├── lib│ └── package.json└── pkg2├── README.md├── tests├── lib└── package.json
给两个 package 增加公共依赖
给 pkg1 和 pkg2 这两个包都安装 fs-extra 这个包,pkg1 和 pkg2 的 package.json 的 dependency 会同时包含 fs-extra 这个包。
$ lerna add fs-extra
安装 fs-extra 之后的目录结构:
lerna-demo├── README.md├── lerna.json├── package.json└── packages├── pkg1│ ├── README.md│ ├── tests│ ├── lib│ ├── node_modules│ ├── package-lock.json│ └── package.json└── pkg2├── README.md├── tests├── lib├── node_modules├── package-lock.json└── package.json
给某个包单独安装指定依赖
比如给 pkg1 安装一个 glob 包,给 pkg2 安装一个 ora 包:
lerna add ora --scope pkg2
其中 --scope 参数用来指定具体给哪个 package 安装包,注意 --scope 后面的参数是对应模块的 package.json 中的 name 字段名。
添加内部模块之间的依赖
将 pkg1 作为 pkg2 的依赖进行安装:
$ lerna add pkg1 --scope pkg2
需要注意的是,通过这种方式安装的依赖,并不会将 pkg1 安装到 pkg2 的 node_modules 里,而是通过 symlink 的形式进行关联。
发布
以上包确认没有问题之后,就可以通过执行 lerna publish 进行发布了。
在进行 publish 之前需要首先提交你的代码,否则 lerna 会报错:
lerna ERR! ENOCOMMIT No commits in this repository. Please commit something before using version.
提交代码并关联到 git 仓库:
git commit -m 'init' git push -u origin main
删除某个包
将 pkg1 里面的 glob 包删除:
$ lerna exec --scope=pkg1 npm uninstall glob
抽离公共的包
上面可以看到,pkg1 和 pkg2 都依赖了 fs-extra 这个包,而各自 package 下面的 node_modules 都进行了一次安装,因此我们可以通过 --hoist 来抽取重复的依赖到最外层的 node_modules 目录下,同时最外层的 package.josn 的依赖信息也不会进行更新。
$ lerna bootstrap --hoist 但是这种方式会有一个问题,不同版本号只会保留使用最多的版本,这种配置不太好,当项目中有些功能需要依赖老版本时,就会出现问题,因此这种方式不推荐使用。
最佳实践
前面我们已经介绍了 lerna 的相关概念和基本用法,目前最常见的解决方案是基于 lerna 和 yarn workspace 的 monorepo 工作流。
由于 yarn 和 lerna 在功能上有较多的重叠,我们采用 yarn 官方推荐的做法:用 yarn 来处理依赖问题,用 lerna 来处理发布问题。
yarn workspaces 与 lerna
yarn workspaces 是 yarn 提供的 monorepo 的依赖管理机制,用于在代码仓库的根目录下管理多个 package 依赖,与 lerna 不同的是,yarn workspaces 可以解决前面说的当不同的 package 依赖不同的版本号问题,yarn workspaces 会检查每个子项目里面依赖及其版本,如果版本不一致都会安装到各自 package 的 node_modules 中,只有依赖版本号一致的时候才会提升到顶层,而 lerna 会进到每个 package 中执行 yarn/npm install,因此会在每个 package 下生成一个 node_modules。
yarn workspaces 首先在工程的根目录下的 package.json 中增加 "private": true 和 "workspaces”: [ "packages/"] 配置项。"private": true 可以确保根目录不会被发布出去,"workspaces”: [ "packages/"] 声明了 workspaces 中所包含的项目路径。
package.json 配置文件增加如下配置。
开启 yarn workspaces
{"private": true,"workspaces": ["packages/*"],}lerna.json 配置文件增加如下配置。{"useWorkspaces": true,"npmClient": "yarn",}
工程初始化
对于一个已经存在的 monorepo 仓库,使用 yarn install 安装依赖。yarn install 会自动安装依赖并且解决同一个仓库之间多个 package 之间的 link 问题。
yarn install 等价于 lerna bootstrap --npm-client yarn --use-workspace。
清理环境
使用 lerna clean 可以清理每个 package 下的 node_modules,但是没有办法清理根目录下的 node_modules 目录,因此,我们可以在根目录下的 package.json 目录的 scripts 中增加一条 clean 命令,用于清理环境。
package.json:{"clear-all": "rimraf node_modules && lerna clean -y"}
安装依赖
安装依赖一般分为三种情况:
安装到 workspace-root
对于一些打包工具或者代码规范校验工具,可以使用 yarn -W add [package] [--dev] 进行安装,比如 typescript、eslint、cross-env、babel、rollup 等。这类包一般都是一些开发依赖,比如将 ts 代码转换成 es5 代码或者一些代码校验工具等。通过这种方式安装的依赖包是装在根目录下的 node_modules 中。
给所有的 package 都安装依赖
比如如果想给每个 package 都安装一个 lodash 包,就可以使用 yarn workspace add lodash 给每个 package 都安装 lodash。
删除包的时候只需要把上述 add 换成 remove 即可。
通过运行 yarn workspace <workspace_name> <command> 命令运行某个执行 package 下的某个 script 命令。
比如执行 pkgA 下的 build 命令,可以运行 yarn workspace pkgA run build。如果想运行 package 下的 build 命令,可以运行 yarn workspaces run build。
代码编写完毕后接下来就涉及到代码的提交,为了规范代码提交格式,方便自动生成 changelog,这里需要借助以下几个工具。
commitizen && cz-conventional-changelogcommitizen 的作用主要是为了生成标准化的 commit message,符合 Angular 规范。
一个标准化的 commit message 应该包含三个部分:Header、Body 和 Footer,其中的 Header 是必须的,Body 和 Footer 可以选填。
<type>(<scope>): <subject>// 空一行<body>// 空一行<footer>
Header 部分由三个字段组成:type(必需)、scope(可选)、subject(必需)
Type
type 必须是下面的其中之一:
feat: 增加新功能
fix: 修复 bug
docs: 只改动了文档相关的内容
style: 不影响代码含义的改动,例如去掉空格、改变缩进、增删分号
refactor: 代码重构时使用,既不是新增功能也不是代码的 bud 修复
perf: 提高性能的修改
test: 添加或修改测试代码
build: 构建工具或者外部依赖包的修改,比如更新依赖包的版本
ci: 持续集成的配置文件或者脚本的修改
chore: 杂项,其他不需要修改源代码或不需要修改测试代码的修改
revert: 撤销某次提交
scope
用于说明本次提交的影响范围。scope 依据项目而定,例如在业务项目中可以依据菜单或者功能模块划分,如果是组件库开发,则可以依据组件划分。
subject
主题包含对更改的简洁描述:
注意三点:
使用祈使语气,现在时,比如使用 "change" 而不是 "changed" 或者 ”changes“
第一个字母不要大写
末尾不要以.结尾
Body
主要包含对主题的进一步描述,同样的,应该使用祈使语气,包含本次修改的动机并将其与之前的行为进行对比。
Footer
包含此次提交有关重大更改的信息,引用此次提交关闭的 issue 地址,如果代码的提交是不兼容变更或关闭缺陷,则 Footer 必需,否则可以省略。
使用方法:
安装 commitizen,如果需要在项目中使用 commitizen 生成符合 AngularJS 规范的提交说明,还需要安装 cz-conventional-changelog 适配器:
$ yarn -W add commitizen cz-conventional-changelog -D
package.json 中增加一条 script: commit: "git-cz",并且在 config 字段中指定 cz-conventional-changelog 路径:
{"name": "root","private": true,"workspaces": ["packages/*"],"scripts": {"commit": "git-cz"},"config": {"commitizen": {"path": "cz-conventional-changelog"}},"devDependencies": {"commitizen": "^4.2.4","cz-conventional-changelog": "^3.3.0","lerna": "^4.0.0"}}
接下来就可以使用 yarn commit 来代替 git commit 进行代码提交了。
commitlint && husky
前面我们提到,通过 commitizen && z-conventional-changelog 可以规范我们的 commit message,但是同时也存在一个问题,如果用户不通过 yarn commit 来提交代码,而是直接通过 git commit 命令来提交代码,就能绕开 commit message 检查,这是我们不希望看到的。
因此接下来我们使用 commitlint 结合 husky 来对我们的提交行为进行约束。在 git commit 提交之前使用 git 钩子来验证信息。提交不符合规则的信息将会被阻止提交。
安装 commitlint 和 husky:
$ yarn -W add @commitlint/cli @commitlint/config-conventional husky -D
在工程根目录下增加 commitlint.config.js 配置文件,指定 commitlint 的校验配置文件:commitlint.config.js:
module.exports = {extends: ['@commitlint/config-conventional']}
需要注意的是,如果安装的 husky 的版本是 7.x 的,以往直接在 package.json 中 hooks 字段增加的配置项已经被废弃了。
已经废弃的配置:
"husky": {"hooks": {"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"}},
下面在 husky 7.x 版本下进行 commit-msg 的配置。
执行 npm husky install
或者如果想在安装后自动启动 husky,在 package.json 的 scripts 中增加一条 script 命令:
"scripts": {"prepare": "husky install"},
prepare 是 NPM 操作生命周期中的一环,在执行 install 的时候会按生命周期顺序执行相应钩子:preinstall -> install -> postinstall -> prepublish -> preprepare -> prepare -> postprepare.
执行完毕后就会在根目录下创建一个 .husky 目录。
通过 husky add <file> [cmd] 指令来添加一条 hook
执行 npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"' 会在 .husky 下生成一个 commit-msg 的 shell 文件:
#!/bin/sh. "0")/_/husky.sh"npx --no-install commitlint --edit "$1"
这样,当我们在执行 git commit -m 'xxx' 的时候,如果提交的 commit message 不符合规范就会报如下的错误,只有提交信息符合提交规范才会允许代码提交。
eslint 配置
配置 eslint 对代码进行统一的规范校验,配合 lint-staged 可以对已经提交的代码进行校验。
安装 eslint 和 lint-stage:
$ yarn -W add eslint lint-staged @typescript-eslint/parser @typescript-eslint/eslint-plugin -D
增加 .eslintrc.js 配置文件:
module.exports = {'parser': '@typescript-eslint/parser','plugins': ['@typescript-eslint'],'rules': {'no-var': 'error',// 不能使用 var 声明变量'no-extra-semi': 'error','@typescript-eslint/indent': ['error', 2],'import/extensions': 'off','linebreak-style': [0, 'error', 'windows'],'indent': ['error', 2, { SwitchCase: 1 }], // error 类型,缩进 2 个空格'space-before-function-paren': 0, // 在函数左括号的前面是否有空格'eol-last': 0, // 不检测新文件末尾是否有空行'semi': ['error', 'always'], // 在语句后面加分号'quotes': ['error', 'single'],// 字符串使用单双引号,double,single'no-console': ['error', { allow: ['log', 'warn'] }],// 允许使用 console.log()'arrow-parens': 0,'no-new': 0,//允许使用 new 关键字'comma-dangle': [2, 'never'], // 数组和对象键值对最后一个逗号
never 参数:不能带末尾的逗号, always 参数:必须带末尾的逗号,always-multiline 多行模式必须带逗号,单行模式不能带逗号
lint-staged staged 是 Git 里的概念,表示暂存区,lint-staged 表示只检查暂存区中的文件。
package.json 中增加如下配置:
"lint-staged": {"*.ts": ["eslint --fix","git add"]}
husky 中增加 pre-commit 校验:
$ npx husky add .husky/pre-commit "npx --no-install lint-staged"
版本发布
通过上面的方式,严格 commit message 的提交规范,就可以方便地通过 lerna 完成生成 changelog、打 git tag、 更新 package.json 的 version 版本号、发布到 npm 等操作。
lerna puplish
lerna publish 的时候会做以下操作:
找出从上一个版本发布以来有过变更的 package
提示开发者确定要发布的版本号
将所有更新过的的 package 中的 package.json 的 version 字段更新
将依赖更新过的 package 的 包中的依赖版本号更新
更新 lerna.json 中的 version 字段
提交上述修改,并打一个 tag
推送到 git 仓库
changelog 的生成可以通过 lerna version --conventional-commits 自动生成,关于 --conventional-commits 参数,lerna 是这么描述的:
Use conventional-changelog to determine version bump and generate CHANGELOG.
在 lerna.json 增加如下配置:
{"command": {"version": {"conventionalCommits": true}},}
lerna version 会检测从上一个版本发布以来的变动,但有一些文件的提交,我们不希望触发版本的变动,譬如 .md 文件的修改,并没有实际引起 package 逻辑的变化,不应该触发版本的变更。可以通过 ignoreChanges 配置排除。
{"ignoreChanges": ["**/*.md"],}
配置好之后,通过 lerna publish 完成 changelog 生成、版本号的修改和 npm 发包等操作了。
总结
以上就是一个完整的基于 lerna + yarn workspace 的 monorepo 的实践流程,里面包含了依赖包的管理、完善的工作流、统一的代码风格、一键发布机制等,当然还有一些不够完善的地方需要自己补充,比如单元测试等,有需要的可以基于上述例子进行补充完善。
版权声明: 本文为 InfoQ 作者【鲸品堂】的原创文章。
原文链接:【http://xie.infoq.cn/article/923f6d6a15c28df1e91a36c25】。文章转载请联系作者。
评论