写点什么

Lerna 最佳实践(内含大量代码)

作者:鲸品堂
  • 2022-10-19
    江苏
  • 本文字数:6409 字

    阅读完需:约 1 分钟

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 多行模式必须带逗号,单行模式不能带逗号


'no-undef': 0},'parserOptions': {'ecmaVersion': 6,'sourceType': 'module','ecmaFeatures': {'modules': true}}};
复制代码


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 的实践流程,里面包含了依赖包的管理、完善的工作流、统一的代码风格、一键发布机制等,当然还有一些不够完善的地方需要自己补充,比如单元测试等,有需要的可以基于上述例子进行补充完善。

发布于: 刚刚阅读数: 3
用户头像

鲸品堂

关注

全球领先的数字化转型专家 2021-03-16 加入

鲸品堂专栏,一方面将浩鲸精品产品背后的领先技术,进行总结沉淀,内外传播,用产品和技术助力通信行业的发展;另一方面发表浩鲸专家观点,品读行业、品读市场、品读趋势,脑力激荡,用远见和创新推动通信行业变革。

评论

发布
暂无评论
Lerna最佳实践(内含大量代码)_代码_鲸品堂_InfoQ写作社区