关于前端:应用级-Monorepo-优化方案

前言

笔者目前所在团队是应用 Monorepo 的形式治理 所有 的业务我的项目，而随着我的项目的增多，稳定性以及开发体验受到挑战，诸多问题开始裸露，能够显著感触到现有的 Monorepo 架构曾经不足以撑持日渐宏大的业务我的项目。

现有的 Monorepo 是基于 yarn workspace 实现，通过 link 仓库中的各个 package，达到跨我的项目复用的目标。package manager 也天经地义的抉择了 yarn，尽管依赖了 Lerna，因为发包场景较为稀少，根本没有怎么应用。

能够总结为以下三点：

• 通过 yarn workspace link 仓库中的 package
• 应用 yarn 作为 package manager 治理我的项目中的依赖
• 通过 lerna 在利用 app 构建前依照依赖关系构建其依赖的 packages

存在的问题

命令不对立

存在三种命令

1. yarn
2. yarn workspace
3. lerna

新人上手容易造成误会，局部命令之间性能存在重叠。

公布速度慢

如果咱们须要公布 app1，则会

1. 全量装置依赖，app1、app2、app3 以及 package1 至 package6 的依赖都会被装置；
2. package 全副被构建，而非仅有 app1 依赖的 package1 与 package2 被构建。

Phantom dependencies

一个库应用了不属于其 dependencies 里的 Package 称之为 Phantom dependencies（幻影依赖、幽灵依赖、隐式依赖），在现有 Monorepo 架构中该问题被放大（依赖晋升）。

因为无奈保障幻影依赖的版本正确性，给程序运行带来了不可控的危险。app 依赖了 lib-a，lib-a 依赖了 lib-x，因为依赖晋升，咱们能够在 app 中间接援用 lib-x，这并不牢靠，咱们是否援用到 lib-x，以及援用到什么版本的 lib-x 齐全取决于 lib-a 的开发者。

NPM doppelgnger

雷同版本的 Package 可能装置多份，打包多份。

假如存在以下依赖关系

最终依赖装置可能存在两种后果：

1. lib-x@^1 * 1 份，lib-x@^2 * 2 份
2. lib-x@^2 * 1 份，lib-x@^1 * 2 份

最终本地会装置 3 份 lib-x，打包时也会存在三份实例，如果 lib-x 要求单例，则可能会造成问题。

Yarn duplicate

Yarn duplicate 及解决方案

假如存在以下依赖关系

当 (p)npm 装置到雷同模块时，判断已装置的模块版本是否合乎新模块的版本范畴，如果合乎则跳过，不合乎则在以后模块的 node_modules 下装置该模块。即 lib-a 会复用 app 依赖的 lib-b@1.1.0。

然而，应用 Yarn v1 作为包管理器，lib-a 会独自装置一份 lib-b@1.2.0。

• difference between npm and yarn behavior with nested dependencies #3951
• Yarn installing multiple versions of the same package
• yarn-deduplicate-Cleans up yarn.lock by removing duplicates.
• Yarn v2 supports package deduplication natively

peerDependencies 危险

Yarn 依赖晋升，在 peerDependencies 场景下可能导致 BUG。

1. app1 依赖 A@1.0.0
2. app2 依赖 B@2.0.0
3. B@2.0.0 将 A@2.0.0 作为 peerDependency，故 app2 也应该装置 A@2.0.0

若 app2 遗记装置 A@2.0.0，那么构造如下

--apps
    --app1
    --app2
--node_modules
    --A@1.0.0
    --B@2.0.0

此时 B@2.0.0 会谬误援用 A@1.0.0。

Package 援用标准缺失

目前我的项目内存在三种援用形式：

1. 源码援用：应用包名援用。须要配置宿主我的项目的构建脚本，将该 Package 纳入构建流程。相似于间接公布一个 TypeScript 源码包，援用该包的我的项目须要做肯定的适配。
2. 源码援用：应用文件门路援用。能够了解“宿主在本身 src 之外的源文件”，即宿主我的项目源代码的一部分，而非 Package。宿主须要提供该所有依赖，在 Yarn 依赖晋升的前提下达到了跨我的项目复用，但存在较大危险。
3. 产物援用。打包实现，间接通过包名援用产物。

Package 援用版本不确定性

假如一个 Monorepo 中的 package1 公布至了 npm 仓库，那么 Monorepo 中的 app1 该当如何在 package.json 中编写援用 package1 的版本号？

package1/packag.json

{
  "name": "package1",
  "version": "1.0.0"
}

app1/package.json

{
  "name": "app1",
  "dependencies": {"package-1": "?" // 这里的版本号应该怎么写？`*` or `1.0.0`}
}

在解决 Monorepo 中我的项目的相互援用时，Yarn 会进行以下几步判断：

1. 判断以后 Monorepo 中，是否存在匹配 app1 所需版本的 package1；
2. 若存在，执行 link 操作，app1 间接应用本地 package1；
3. 若不存在，从远端 npm 仓库拉取合乎版本的 package1 供 app1 应用。

须要特地留神的是：* 无奈匹配 prerelease 版本 👉 Workspace package with prerelease version and wildcard dep version #6719。

假如存在以下场景：

1. package1 此前曾经公布了 1.0.0 版本，此时远端仓库与本地 Monorepo 中代码统一；
2. 产品同学提了一个只服务于 Monorepo 外部利用的需要；
3. package1 在 1.0.0 版本下迭代，无需变更版本号公布；
4. Yarn 判断 Monorepo 中的 package1 版本满足了 app1 所需版本（* 或 1.0.0）；
5. app1 顺利应用上 package1 的最新个性。

直到某天，该需要个性须要提供给内部业务方应用。

1. pacakge1 将版本改为 1.0.0-beta.0 并进行发版；
2. Yarn 判断以后 Monorepo 中的 package1 版本不满足 app1 所需版本；
3. 从远端拉取 package1@1.0.0 供 app1 应用；
4. 远端 package@1.0.0 曾经落后 app1 先前应用的本地 package@1.0.0 太多；
5. 筹备事变通报以及复盘。

这种不确定性，导致援用此类 package 时会常常犯嘀咕：我到底援用的是本地版本还是远端版本？为什么有时候是本地版本，有时候是远端版本？我想用上 package1 的最新内容还须要时刻放弃与 package1 的版本号保持一致，那我干嘛用 Monorepo？

yarn.lock 抵触

(p)npm 反对自动化解决 lockfile 抵触，yarn 须要手动解决，在大型 Monorepo 场景下，简直每次分支合并都会遇到 yarn.lock 抵触。

• 不解决抵触无脑 yarn，yarn.lock 会间接生效，全副版本更新到 package.json 最新，危险太大，失去 lockfile 的意义；
• 人工解决抵触往往会呈现 Git conflict with binary files，只能应用 master 的提交再从新 yarn，流程繁琐。

Automatically resolve conflicts in lockfile · Issue #2036 · pnpm/pnpm

能够发现，现有 Monorepo 治理形式缺点过多，随着其内我的项目的一直减少，构建速度会越来越慢，同时程序的健壮性无奈失去保障。仅凭开发人员盲目是不牢靠的，咱们须要一套解决方案。

举荐浏览：node_modules 窘境

解决方案

pnpm

Fast, disk space efficient package packageManager

在 npm@3 之前，node_modules 的构造是洁净且可预测的，因为 node_modules 中的每个依赖项都有其本人的 node_modules 文件夹，其所有依赖项都在 package.json 中指定。

node_modules
└─ foo
   ├─ index.js
   ├─ package.json
   └─ node_modules
      └─ bar
         ├─ index.js
         └─ package.json

然而这样带来了两个很重大的问题：

1. 依赖层级过深在 Windows 下会呈现问题；
2. 同一 Package 作为其余多个不同 Package 的依赖项时，会被拷贝很屡次。

为了解决这两个问题，npm@3 从新思考了 node_modules 的构造，引入了平铺的计划。于是就呈现了上面咱们所相熟的构造。

node_modules
├─ foo
|  ├─ index.js
|  └─ package.json
└─ bar
   ├─ index.js
   └─ package.json

与 npm@3 不同，pnpm 应用另外一种形式解决了 npm@2 所遇到的问题，而非平铺 node_modules。

在由 pnpm 创立的 node_modules 文件夹中，所有 Package 都与本身的依赖项分组在一起（隔离），然而依赖层级却不会过深（软链接到里面真正的地址）。

-> - a symlink (or junction on Windows)

node_modules
├─ foo -> .registry.npmjs.org/foo/1.0.0/node_modules/foo
└─ .registry.npmjs.org
   ├─ foo/1.0.0/node_modules
   |  ├─ bar -> ../../bar/2.0.0/node_modules/bar
   |  └─ foo
   |     ├─ index.js
   |     └─ package.json
   └─ bar/2.0.0/node_modules
      └─ bar
         ├─ index.js
         └─ package.json

1. 基于非扁平化的 node_modules 目录构造，解决 Phantom dependencies。Package 只可触达本身依赖。
2. 通过软链复用雷同版本的 Package，防止反复打包（雷同版本），解决 NPM doppelgnger（顺带解决磁盘占用）。

能够发现，很多与包管理器相干的问题就此迎刃而解。

• Why should we use pnpm?
• 平铺 node_modules 不是惟一的路

Rush

a scalable monorepo manager for the web

1. 命令对立。

rush(x) xxx 一把梭，缩小新人上手老本。同时 Rush 除了 rush add 以及 rushx xxx 等命令须要在指定我的项目下运行，其余命令均为全局命令，可在我的项目内任意目录执行，防止了在终端频繁切换我的项目门路的问题。

2. 弱小的依赖剖析能力。

Rush 中的许多命令反对剖析依赖关系，比方 -t(to) 参数：

$ rush install -t @monorepo/app1

该命令只会装置 app1 的依赖及其 app1 依赖的 package 的依赖，即按需装置依赖。

$ rush build -t @monorepo/app1

该命令会执行 app1 以及 app1 依赖的 package 的构建脚本。

相似的，还有 -f(from) 参数，能够使命令只作用于以后 package 以及依赖了该 package 的 package。

3. 保障依赖版本一致性

Monorepo 中的我的项目该当尽量保障依赖版本的一致性，否则很有可能呈现反复打包以及其余的问题。

Rush 则提供了许多能力来保障这一点，如rush check、rush add -p package-name -m 以及 ensureConsistentVersions。

有趣味的同学能够自行翻阅 Rush 的官网文档，非常详尽，对于一些常见问题也有阐明。

Package 援用标准

产物援用

传统援用形式，构建实现后，app 间接援用 package 的构建产物。开发阶段能够通过构建工具提供的能力保障实时构建（如 tsc –watch）

• 长处：标准，对 app 敌对。
• 毛病：随着模块增多，package 热更新速度可能变得难以忍受。

源码援用

package.json 中的 main 字段配置为源文件的入口文件，援用该 package 的 app 须要将该 package 纳入编译流程。

• 长处：借助 app 的热更新能力，本身没有生成构建产物的过程，热更新速度快
• 毛病：须要 app 进行适配，alias 适配繁琐；

援用标准

1. 对于我的项目外部应用的 packages，称为 features，不该当向外公布，间接将 main 字段设置为源文件入口并配置 app 我的项目的 webpack，走后编译模式。
2. 对于须要对外公布的 packages，不应该也不容许援用 features，必须要有构建过程，如果须要应用源码开发减少热更新速度，能够新增一个自定义的入口字段，app 的 webpack 配置中优先辨认该入口字段即可。

补充：rush build 命令是反对构建产物缓存的，如果 app 拆分粒度够小，可复用的包足够多，同时打包镜像反对构建产物缓存的 set 与 get，就能够做到增量构建 app。

Workspace protocol (workspace:)

在 PNPM 和 Yarn 反对 Workspace 能力之前，Rush 就诞生了。Rush 的办法是将所有软件包集中装置在 common / temp 文件夹中，而后 Rush 创立从每个我的项目到 common / temp 的符号链接。与 PNPM Workspace 实质上是等效的。

开启 PNPM workspace 能力从而能够应用 workspace: 协定保障援用版本的确定性，应用了该协定援用的 package 只会应用 Monorepo 中的内容。

{
  "dependencies": {
    "foo": "workspace:*",
    "bar": "workspace:~",
    "qar": "workspace:^",
    "zoo": "workspace:^1.5.0"
  }
}

举荐援用 Monorepo 内的 package 时对立应用该协定，援用本地最新版本内容，保障更改可能及时扩散同步至其余我的项目，这也是 Monorepo 的劣势所在。

若肯定要应用远端版本，须要在 rush.json 中配置具体 project（减少 cyclicDependencyProjects 配置），详见 rush_json。

很侥幸的是 PNPM workspace 中 workspace:* 能够匹配 prerelease 版本 👉 Local prerelease version of packages should be linked only if the range is *

问题记录

Monorepo Project Dependencies Duplicate

这个问题相似于后面提到的 Yarn duplicate，但并不是 Yarn 独有的。

假如存在以下依赖关系（将 Yarn duplicate 的例子进行革新，放在 Monorepo 场景中）

app1 以及 package1 同属于 Monorepo 外部 project。

在 Rush(pnpm)/Yarn 我的项目中，会严格依照 Monorepo 内 project 的 package.json 所申明的版本进行装置，即 app1 装置 lib-a@1.1.0，package1 装置 lib-a@1.2.0。

此时对 app1 进行打包，则 lib-a@1.1.0 和 lib-a@1.2.0 都会被打包。

对这个后果你兴许会有一些意外，但认真想想，又很天然。

换一种形式了解，整个 Monorepo 是一个大的虚构 project，咱们所有的 project 都作为这个虚构 project 的间接依赖存在。

{
  "name": "fake-project",
  "version": "1.0.0",
  "dependencies": {
    "@fake-project/app1": "1.0.0",
    "@fake-project/package1": "1.0.0"
  }
}

装置依赖时，(p)npm 首先下载 间接依赖项 ，而后再下载 间接依赖项，并且在装置到雷同模块时，判断已装置的模块版本（间接依赖项）是否合乎新模块（间接依赖项）的版本范畴，如果合乎则跳过，不合乎则在以后模块的 node_modules 下装置该模块。

而 app1 和 package1 的间接依赖关系 lib-a 是该 fake-project 的间接依赖项，无奈满足上述判断条件，于是依照对应 package.json 中形容的版本装置。

解决方案：Rush: Preferred versions

Rush 能够通过手动指定 preferredVersions 的形式，防止两个可兼容版本的反复。这里将 Monorepo 中 lib-a 的 preferredVersions 指定为 1.2.0，相当于在该虚构 project 下间接装置了指定的版本的模块，作为间接依赖项。

{
  "name": "fake-project",
  "version": "1.0.0",
  "dependencies": {
    "@fake-project/app1": "1.0.0",
    "@fake-project/package1": "1.0.0",
    "lib-a": "1.1.0"
  }
}

对于 Yarn，因为 Yarn duplicate 的存在，就算在根目录指定装置确定版本的 lib-a 也是有效的。
然而仍旧有两种计划能够进行解决：

1. 通过 yarn-deduplicate 针对性的批改 yarn.lock；
2. 应用resolutions 字段。过于粗犷，不像 preferredVersions 能够容许不兼容版本的存在，不举荐。

须要谨记：在 Yarn 下打消反复依赖，也应该一个 Package 一个 Package 的去进行解决，小心使得万年船。

1. 对于存在副作用的公共库，版本最好放弃对立；
2. 对于其余的体积小（或反对按需加载）、无副作用的公共库，反复打包在肯定水平上能够承受的。

prettier

因为根目录不再存在 node_modules，故须要每个我的项目装置一个 prettier 作为 devDependency 并编写 .prettierrc.js 文件。

本着偷懒的准则，根目录新建 .prettierrc.js（不依赖任何第三方包），全局装置 prettier 解决该问题。

eslint

先看一个场景，若在我的项目中应用 eslint-config-react-app，除了须要装置 eslint-config-react-app，还须要装置一系列 peerDependencies 插件。

为什么 eslint-config-react-app 不将这一系列插件作为 dependencies 内置，而是作为 peerDependencies？使用者并不需要关怀预设配置内援用了哪些插件。

具体探讨能够查看该 issue，外面有相干问题的探讨：Support having plugins as dependencies in shareable config #3458。

总而言之：和 eslint 插件的具体查找形式无关，如果因为依赖晋升失败（多版本抵触），导致须要的插件被装在了非根目录 node_modules 下，就可能产生问题，而用户自行装置 peerDependencies 能够保障不会呈现该问题。

当然，咱们也发现一些开源的 eslint 预设配置不须要装置 peerDependencies，这些预设利用了 yarn 和 npm 的扁平 node_modules 构造，也就是依赖晋升，装的包都被晋升至根目录 node_modules，故能够失常运作。即便如此，在基于 Yarn 的 Monorepo 中，依赖一旦简单起来，就可能呈现插件无奈被查找到的状况，可能失常运行就像一个乏味的偶合。

在 Rush 中，不存在依赖晋升（晋升也不肯定靠谱），装一系列的插件又过于繁琐，则能够通过打补丁的形式绕过。

git hooks

通常会在我的项目中应用 husky 注册 pre-commit 和 commit-msg 钩子，用于校验代码格调以及 commit 信息。

很显著，在 Rush 我的项目的构造下，根目录是没有 node_modules 的，无奈间接应用 husky。

咱们能够借助 rush init-autoinstaller 的能力来达到一样的成果，本节次要参考官网文档 Installing Git hooks 以及 Enabling Prettier 的内容。

# 初始化一个名为 rush-lint 的 autoinstaller

$ rush init-autoinstaller --name rush-lint

$ cd common/autoinstallers/rush-lint

# 装置 lint 所需依赖

$ pnpm i @commitlint/cli @commitlint/config-conventional @microsoft/rush-lib eslint execa prettier lint-staged

# 更新 rush-lint 的 pnpm-lock.yaml

$ rush update-autoinstaller --name rush-lint

在 rush-lint 目录下新增 commit-lint.js 以及 commitlint.config.js，内容如下

commit-lint.js

const path = require('path');
const fs = require('fs');
const execa = require('execa');

const gitPath = path.resolve(__dirname, '../../../.git');
const configPath = path.resolve(__dirname, './commitlint.config.js');
const commitlintBinPath = path.resolve(__dirname, './node_modules/.bin/commitlint');

if (!fs.existsSync(gitPath)) {console.error('no valid .git path');
    process.exit(1);
}

main();

async function main() {
    try {await execa('bash', [commitlintBinPath, '--config', configPath, '--cwd', path.dirname(gitPath), '--edit'], {stdio: 'inherit',});
    } catch (\_e) {process.exit(1);
    }
}

commitlint.config.js

const rushLib = require("@microsoft/rush-lib");

const rushConfiguration = rushLib.RushConfiguration.loadFromDefaultLocation();

const packageNames = [];
const packageDirNames = [];

rushConfiguration.projects.forEach((project) => {packageNames.push(project.packageName);
  const temp = project.projectFolder.split("/");
  const dirName = temp[temp.length - 1];
  packageDirNames.push(dirName);
});
// 保障 scope 只能为 all/package name/package dir name
const allScope = ["all", ...packageDirNames, ...packageNames];

module.exports = {extends: ["@commitlint/config-conventional"],
  rules: {"scope-enum": [2, "always", allScope],
  },
};

留神：此处不须要新增 prettierrc.js（根目录已存在）以及 eslintrc.js（各我的项目已存在）。

根目录新增 .lintstagedrc 文件

.lintstagedrc

{"{apps,packages,features}/**/*.{js,jsx,ts,tsx}": [
    "eslint --fix --color",
    "prettier --write"
  ],
  "{apps,packages,features}/**/*.{css,less,md}": ["prettier --write"]
}

实现了相干依赖的装置以及配置的编写，咱们接下来将相干命令执行注册在 rush 中。

批改 common/config/rush/command-line.json 文件中的 commands 字段。

{
  "commands": [
    {
      "name": "commitlint",
      "commandKind": "global",
      "summary": "Used by the commit-msg Git hook. This command invokes commitlint to lint commit message.",
      "autoinstallerName": "rush-lint",
      "shellCommand": "node common/autoinstallers/rush-lint/commit-lint.js"
    },
    {
      "name": "lint",
      "commandKind": "global",
      "summary": "Used by the pre-commit Git hook. This command invokes eslint to lint staged changes.",
      "autoinstallerName": "rush-lint",
      "shellCommand": "lint-staged"
    }
  ]
}

最初，将 rush commitlint 以及 rush lint 两个命令别离与 commit-msg 以及 pre-commit钩子进行绑定。
common/git-hooks 目录下减少 commit-msg 以及 pre-commit 脚本。

commit-msg

#!/bin/sh

node common/scripts/install-run-rush.js commitlint || exit $? #++

pre-commit

#!/bin/sh

node common/scripts/install-run-rush.js lint || exit $? #++

如此，便实现了需要。

防止全局装置 eslint 以及 prettier

通过上一节的解决，在 rush-lint 目录下装置了 eslint 以及 prettier 后，咱们便无需全局装置了，只须要配置一下 VSCode 即可。

{
  // ...
  "npm.packageManager": "pnpm",
  "eslint.packageManager": "pnpm",
  "eslint.nodePath": "common/autoinstallers/rush-lint/node_modules/eslint",
  "prettier.prettierPath": "common/autoinstallers/rush-lint/node_modules/prettier"
  // ...
}

附录

常用命令

工作流

# 从 git 拉取最新变更
$ git pull

# 更新 NPM 依赖
$ rush update

# 从新打包 @monorepo/app1 依赖的我的项目（不含包其自身）$ rush rebuild -T @monorepo/app1

# 进入指定我的项目目录
$ cd ./apps/app1

# 启动我的项目 ​
$ rushx start # or rushx dev

参考文章

• Rush.js
• node_modules 窘境
• Why should we use pnpm?
• 平铺 node_modules 不是惟一的路