Monorepo实战

场景

维护多个仓库的公共代码是一件头疼的事情，每次对公共代码的改动都要全量仓库同步，最后决定用 monorepo 改造一番。

Monorepo

Monorepo(monolithic repository) 是管理项目代码的一个方式，指在一个项目仓库 (repo) 中管理多个模块/包 (package)，不同于常见的每个模块建一个 repo。

目前不少大型开源项目采用了这种方式，如 Babel、React、Vue 等。monorepo 管理代码只要搭建一套脚手架，就能管理（构建、测试、发布）多个 package。

在项目的第一级目录的内容以脚手架为主，主要内容都在 packages 目录中、分多个 package 进行管理。目录结构大致如下：

├── packages
|   ├── pkg1
|   |   ├── package.json
|   ├── pkg2
|   |   ├── package.json
├── package.json

此时会有一个问题，虽然拆分子 npm 包管理项目简单了很多，但是当仓库内容有关联时，调试变得困难。所以理想的开发环境应该是只关心业务代码，可以直接跨业务复用而不关心复用方式，调试时所有代码都在源码中。

目前最常见的 monorepo 解决方案是 lerna 和 yarn 的 workspaces 特性。用 yarn 处理依赖问题，lerna处理发布问题。

Lerna

Lerna是npm模块的管理工具，为项目提供了集中管理package的目录模式，如统一的 repo 依赖安装、package scripts和发版等特性。

安装

建议全局安装

npm i -g lerna

初始化项目

lerna init

初始化后，会生成 packages 空目录和 package.json 和 lerna.json 配置文件，配置文件如下:

//package.json
{
  "name": "root",
  "private": true, // 私有的，不会被发布，是管理整个项目，与要发布的npm包解耦
  "devDependencies": {
    "lerna": "^3.22.1"
  }
}

//lerna.json
{
  "packages": [
    "packages/*"
  ],
  "version": "0.0.0"
}

创建npm包

执行命令后可修改包信息，这里创建 @monorepo/components 和 @monorepo/utils

lerna create @monorepo/components

安装依赖

lerna和yarn workspace安装依赖的方法都鸡肋

lerna add lodash // 为所有 package 增加 lodash 模块 

// 为 @monorepo/utils 增加 lodash 模块(lodash可替换为内部模块，如@monorepo/components)
lerna add lodash --scope @monorepo/utils  

lerna add的鸡肋之处是一次只能安装一个包...

依赖包管理

一般情况下 package 的依赖都是在各自的 node_modules 目录下，这不仅增加了包的安装和管理成本，还可能会出现同一个依赖有多个的情况。所以可把所有 package 的依赖包都提升到工程根目录。

lerna 和 yarn workspace都可以把依赖包提升到 repo 根目录管理。lerna 在安装依赖时（lerna bootstrap）提供了--hoist选项，但其鸡肋的地方在于，由于 lerna 直接以字符串对比 dependency 的版本号，同一个依赖在版本号完全相同时才会提升到根目录下，举个栗子：

A 依赖了 @babel/core@^7.10.0
B 依赖了 @babel/core@^7.11.4

lerna 会在 A 的 node_modules 目录下安装 7.11.4 版本的 babel/core，并在 A 目录下生成了一份 package-lock.json，这无疑加大了维护成本和包的体积。

而yarn workspace在这种情况下只会在根目录有一份yarn-lock.json，也不会重复在子目录下安装依赖。

yarn workspace

搭建环境

主要是为安装依赖的配置调整。

在monorepo管理的项目中，各个库之间存在依赖，如A依赖于B，因此我们通常需要将B link到 A 的node_module里，一旦仓库很多的话，手动的管理这些link操作负担很大，因此需要自动化的link操作，按照拓扑排序将各个依赖进行link

解决方式：通过使用 workspace，yarn install 会自动的帮忙解决安装和 link 问题

yarn install # 等价于 lerna bootstrap --npm-client yarn --use-workspaces

package.json & lerna.json 如下:

//lerna.json
{
  "packages": ["packages/*"],
  "npmClient": "yarn",
  "useWorkspaces": true, // 使用yarn workspaces
  "version": "0.0.0"
}

//package.json
{
  "name": "root",
  "private": true,
  "workspaces": [ //指定workspace路径
    "packages/*"
  ],
  "devDependencies": {
    "lerna": "^3.22.1"
  }
}

清理环境

在依赖乱掉或者工程混乱的情况下，清理依赖

lerna clean # 清理所有packages的node_modules目录，不能删除根目录的node_modules
yarn workspaces run clean # 执行所有package的clean操作（应是需自行写脚本）

大部分资料都说lerna clean可以删除根目录的依赖，实际感觉是不行，官网原话是
lerna clean does not remove modules from the root node_modules directory, even if you have the --hoist option enabled.

安装/删除依赖

一般分为三种场景

• 给某个 package 安装/删除依赖
• 给 root 安装/删除依赖，一般的公用的开发工具都是安装在 root 里，如 typescript
• 给所有 package 安装/删除依赖

关于最后一种情况，网上均显示 yarn workspaces add/remove lodash 可以给所有包安装/删除依赖，然而用就是报错 - error Invalid subcommand. Try "info, run"，yarn 2.0 只能用 yarn workspaces foreach，运行前要装 workspace-tools 插件，但还没有时间尝试过...所以这里只说前两种情况。

安装/删除依赖对应场景依次如下：

yarn workspace packageA add/remove packageB [packageC -D] //为 packageA 安装/删除 packageB、C 依赖
yarn add/remove typescript -W -D // 给 root 安装/删除 typescript

需注意一点，当使用 yarn workspace packageA add xxx 安装时，将会再次安装 packageA 的所有依赖且安装在到 packageA 目录下。

对于安装local dependency，yarn的实现暂时有bug，第一次安装需要指明版本号，否则会安装失败如下
如果ui-button没有发布到 npm 则 yarn workspace ui-form add ui-button 会安装失败，但是 yarn workspace ui-form add ui-button@1.0.0会成功 ，详情

安装完依赖文件结构如下：

提交规范

在构建和发布之前还需要做一些关于代码提交的配置

commitizen && cz-lerna-changelog

commitizen 是用来格式化 git commit message 的工具，它提供了一种问询式的方式去获取所需的提交信息。

cz-lerna-changelog 是专门为 Lerna 项目量身定制的提交规范，在问询的过程，会有类似影响哪些 package 的选择。如下：

我们使用 commitizen 和 cz-lerna-changelog 来规范提交，为后面自动生成日志作好准备。
因为这是整个工程的开发依赖，所以在根目录安装：

yarn add commitizen cz-lerna-changelog -D -W

安装完成后，在 package.json 中增加 config 字段，把 cz-lerna-changelog 配置给 commitizen。同时因为commitizen不是全局安全的，所以需要添加 scripts 脚本来执行 git-cz

{
  "name": "monorepo",
  "private": true,
  "workspaces": [
    "packages/*"
  ],
  "scripts": {
    "commit": "git-cz"
  },
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-lerna-changelog"
    }
  },
  "devDependencies": {
    "commitizen": "^4.2.1",
    "cz-lerna-changelog": "^2.0.3",
    "lerna": "^3.22.1"
  }
}

之后在常规的开发中就可以使用 yarn run commit 来根据提示一步一步输入，来完成代码的提交。

commitlint && husky

以下配置是强制开发者遵循上述规范，可暂时跳过，因为提交起来略久……

上面我们使用了 commitizen 来规范提交，但很难靠开发自觉使用 yarn run commit 。万一忘记了，或者直接使用 git commit 提交怎么办？所以在提交时校验提交信息，如果不符合要求就不让提交，并提示。校验的工作由 commitlint 来完成，校验的时机则由 husky 来指定。husky 继承了 Git 下所有的钩子，在触发钩子的时候，husky 可以阻止不合法的 commit，push 等等。

安装 commitlint 以及要遵守的规范：

yarn add -D -W husky @commitlint/cli @commitlint/config-conventional

在工程根目录为 commitlint 增加配置文件 commitlint.config.js 为commitlint 指定相应的规范

module.exports = { 
    extends: ['@commitlint/config-conventional'] 
}

在 package.json 中增加如下配置

"husky": { 
        "hooks": { 
            "commit-msg": "commitlint -E HUSKY_GIT_PARAMS" 
     }
 }

"commit-msg"是git提交时校验提交信息的钩子，当触发时便会使用 commitlint 来校验。安装配置完成后，想通过 git commit 或者其它第三方工具提交时，只要提交信息不符合规范就无法提交。从而约束开发者使用 yarn run commit 来提交。

eslint && lint-staged

原本想先跳过eslint的规范的……然而如果项目已经有eslint，而npm包没有，调试都会报错，原以为一个.eslintlrc文件和装eslint插件就能解决问题，然而并没有这么简单，累了……后期补上解决问题的过程

除了规范提交信息，代码本身肯定也少了靠规范来统一风格。

yarn add -D -W standard lint-staged

eslint就是完整的一套 JavaScript 代码规范，自带 linter & 代码自动修正。自动格式化代码并修正，提前发现风格以及程序问题, 同时也支持javascript的代码规范校验，eslintrc.json：

module.exports = {
  env: {
    browser: true,
    es2020: true
  },
  extends: ["eslint:recommended", "plugin:vue/essential"],
  parserOptions: {
    parser: "babel-eslint"
  },
  plugins: ["vue"],
  rules: {
    "prettier/prettier": [
      "off",
      {
        quotes: 0
      }
    ]
  }
}

lint-staged staged 是 Git 里的概念，表示暂存区，lint-staged 表示只检查并矫正暂存区中的文件。一来提高校验效率，二来可以为老的项目带去巨大的方便。

package.json配置

{
  "name": "monorepo",
  "private": true,
  "workspaces": [
    "packages/*"
  ],
  "scripts": {
    "c": "git-cz"
  },
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-lerna-changelog"
    }
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.(vue|js)": [
      //"eslint --fix",
      "prettier --write"
    ]
  },
  "devDependencies": {
    "commitizen": "^4.2.1",
    "cz-lerna-changelog": "^2.0.3",
    "lerna": "^3.22.1",
    "lint-staged": "^10.2.13",
    "standard": "^14.3.4"
  }
}

安装完成后，在 package.json 增加 lint-staged 配置 "prettier --write"，校验时机定在pre-commit，在husky的配置中增加pre-commit的钩子用来执行 lint 校验。

eslint --fix 校验并自动修复慎用，分分钟提交不了……

使用 Lerna 构建和发布

项目构建

各个package之间存在相互依赖，如packageB只有在packageA构建完之后才能进行构建，否则就会出错，这实际上要求我们以一种拓扑排序的规则进行构建。

我们可以自己构建拓扑排序规则，很不幸的是yarn的workspace暂时并未支持按照拓扑排序规则执行命令,虽然该 rfc已经被accepted，但是尚未实现

幸运的是lerna支持按照拓扑排序规则执行命令, --sort参数可以控制以拓扑排序规则执行命令

lerna run --stream --sort build

可在根目录的package.json下配置

"scripts": {
    "build": "lerna run --stream --sort build"
  },

版本升级及发包

历经重重困难终于到了发布最后一步了

项目测试完成后，就涉及到版本发布，版本发布一般涉及到如下一些步骤

• 条件验证: 如验证测试是否通过，是否存在未提交的代码，是否在主分支上进行版本发布操作
• version_bump:发版的时候需要更新版本号，这时候如何更新版本号就是个问题，一般大家都会遵循 semVer语义
• 生成changelog: 为了方便查看每个package每个版本解决了哪些功能，我们需要给每个package都生成一份changelog方便用户查看各个版本的功能变化。
• 生成git tag：为了方便后续回滚问题及问题排查通常需要给每个版本创建一个git tag
• git 发布版本：每次发版我们都需要单独生成一个commit记录来标记milestone
• 发布npm包：发布完git后我们还需要将更新的版本发布到npm上，以便外部用户使用

yarn官方并不打算支持发布流程，只是想做好包管理工具，因此这部分还是需要通过lerna支持

lerna提供了publish和version来支持版本的升级和发布, publish的功能可以即包含version的工作，也可以单纯的只做发布操作。

只发布某个package

lerna官方不支持仅发布某个package，https://github.com/lerna/lerna/issues/1691，如果需要，只能自己手动的进入package进行发布，这样lerna自带的各种功能就需要手动完成且可能和lerna的功能相互冲突

由于 lerna 会自动的监测 git 提交记录里是否包含指定 package 的文件修改记录，来确定版本更新，这要求设置好合理的 ignore 规则（否则会造成频繁的，无意义的某个版本更新），好处是其可以自动的帮助 package 之间更新版本

例如如果 ui-form 依赖了 ui-button，如果 ui-button 发生了版本变动，会自动的将 ui-form 的对 ui-button 版本依赖更新为 ui-button 的最新版本。 如果 ui-form 发生了版本变动，对 ui-button 并不会造成影响。

经测试 version_bump 是依赖于文件检测和 subject 结合，并不依赖于 scope，scope 的作用是用来生成 changelog 的吧，即如果是修改了 ui-form 的文件，但是 commit 记录写的是 fix(ui-button)，lerna 是会生成 ui-form 的版本更新，并不会去更新 ui-button 的版本。

发布自动生成日志

有了之前的规范提交，自动生成日志便水到渠成了。leran publish 时主要做了以下事情：

lerna version 更新版本

• 找出从上一个版本发布以来有过变更的 package
• 提示开发者确定要发布的版本号
• 将所有更新过的的 package 中的package.json的version字段更新
• 将依赖更新过的 package 的 包中的依赖版本号更新
• 更新 lerna.json 中的 version 字段
• 提交上述修改，并打一个 tag

• 推送到 git 仓库

  
  

lerna publish

版本自动更新可使用--conventional-commits 参数会自动的根据conventional commit规范和git commit message记录帮忙确定更新的版本号：

// lerna.json
{
  "packages": ["packages/*"],
  "npmClient": "yarn",
  "useWorkspaces": true,
  "command": {
    "version": {
      "conventionalCommits": true # 生成changelog文件以及根据commit来进行版本变动
    }
  },
  "ignoreChanges": ["**/*.md"], # md文件更新，不触发版本变动
  "version": "0.0.0"
}

最后包内的 package.json 还需 publishConfig 配置

"publishConfig": {
   "access": "publish" // 如果该模块需要发布，对于scope模块，需要设置为publish，否则需要权限验证
  }

最后

lerna publish [from-git]

如果第一次没发成功但是却显示成功了，则要加from-git才能重新发，发布也还有一些坑……

完善的测试用例

monorepo项目：测试有两种方式

• 使用统一的 jest 测试配置这样方便全局的跑 jest 即可，好处是可以方便统计所有代码的测试覆盖率，坏处是如果 package 比较异构（如小程序，前端，node 服务端等），统一的测试配置不太好编写
• 每个 package 单独支持test命令，使用 yarn workspace run test，坏处是不好统一收集所有代码的测试覆盖率

此处附上 typescript 的测试例子，初始化配置 jest.config.js：

module.exports = {
  preset: 'ts-jest',
  moduleFileExtensions: ['ts'],
  testEnvironment: 'node'
}

最后附上 github 地址：https://github.com/moon-bonny/monorepo

readme 还未来得及完善……

未完待续……

后续有时间再出踩坑篇和vue组件打包篇