Monorepo 下的模块包设计实践

date
Jan 12, 2022
slug
monorepo-pkg
status
Published
tags
Node.js
React
Web
Monorepo
summary
主要面向前端、Node.js 开发者,业务中使用 Monorepo 组织 应用 和 模块,抛砖引玉探讨下:怎样设计一个共享配置包? UI 组件库怎么打包?怎么使用原生语言(Rust / C++ / Golang 等)编写的模块包?
type
Post

前言

本文主要面向前端、Node.js 开发者,业务中使用 Monorepo 组织 应用模块,抛砖引玉探讨下:
  1. 怎样设计一个共享配置包(配置、类型、utils、枚举),同时在前端、Node.js、Vite 等项目中使用
  1. UI 组件库怎么打包?组件库怎么支持服务端渲染(SSR)?有哪些好的最佳实践?
  1. 怎么使用原生语言(Rust / C++ / Golang 等)编写的模块包?
本文演示的代码仓库见:monorepo(使用 pnpm,其它 Monorepo 工具同理)
notion image
 

为什么设计模块包?

随着 Monorepo 代码越堆越多、多人员协作情况下,不可避免遇到如下问题:
  • 重复定义问题:工具方法、类型、配置在不同应用之间重复定义,维护困难。(例如:一个应用类型 AppType 的定义可以达 10 多处,很多还是旧的定义;项目用到配置; tsconfig.json 、prettier 等相同的配置写一遍又一遍)
notion image
  • 依赖管理问题:为解决重用问题,我们也试过将模块先发成 npm 包,但发完需要更新应用 package.json 中的依赖版本,一来一回非常折腾。
  • 跨项目使用问题:同构就是指 模块同时跑在前后端项目,兼容不同的模块包规范(CommonJS、ESM 等)。如果没有很好的设计包结构,经常会在项目编译打包时报错 ❌
notion image

有哪些类型的模块包?

由于历史原因,JavaScript 模块化系统一直没有统一规范,大致发展过程是:CJS → AMD → CMD → UMD → ESM,这给设计一个跨应用使用的模块带来不少麻烦。
在设计模块包之前,有必要先了解下目前主流的模块类型和规范(esm、cjs、umd)。
模块类型/格式/规范
描述
导出语法
使用语法
备注
JavaScript 官方的标准化模块系统(草案),在标准化道路上花了近 10 年时间。 适用于: Browser Node.js ≥ 12.17
export default foo export const foo = 1; export { bar as foo } from ''
import foo from 'name' import { foo } from 'name' import { foo as bar } from 'name' <script type="module" src="."/> <script type="module"> import { bar } from 'name'; </script>
Node.js 的模块标准,文件即模块。 适用于: Node.js
module.exports = foo exports.foo = 1;
const foo = require('name'); const { foo } = require('name');
umd 严格意义上不算规范,只是社区出的通用包模块结合体的格式,兼容 CJS 和 AMD 格式。 浏览器端用来挂载全局变量 (如:window.*适用于: Browser(external 场景Node.js(较少)
(function (root, factory) { if (// amd) { } else if (//cjs) { } else (//global) { } })(this, function() {})
window.React window.ReactDOM $
通过上面模块的对比,对于现阶段选择模块规范最佳实践是:
  • 共享配置模块(跨前后端):同时打出 ESMCJS 格式的包(目前 Node.js 运行时对 ESM 支持不是很好)
  • UI 组件库:同时打出 ESMCJSUMD(umd 主要是为了让前端项目可以做 external,减少构建时长)
  • 面向 Node.js 项目:目前只需要打出 CJS 格式

package.json 模块声明

如果模块设计是一门艺术,package.json 就是这门艺术的说明书!在实际开发过程中,有不少开发者并不能正确配置 package.json。

基础信息

大部分字段来源于 npm 官方 的定义,描述一个包的基础信息:
// package.json { // 包名(示例:import {} from 'your-lib') "name": "your-lib", "version": "1.0.0", "description": "一句话介绍你的包", // 发布到 npm 上的目录,不同于 `.npmignore` 黑名单,`files` 是白名单 "files": ["dist", "es", "lib"], // 安全神器,不发到 npm 上 "private": true, /** * 包依赖 */ // 运行时依赖,包消费者会安装的依赖 "dependencies": { "lodash": "^4.17.21", // ❌ "webpack": "^5.0.0", // ❌ "react": "^17.0.0" 不推荐将 react 写进依赖 }, "peerDependencies": { "react": "^16.0.0 || ^17.0.0", "react-dom": "^16.0.0 || ^17.0.0" }, // 开发时依赖,使用方不会安装到,只为包开发者服务 "devDependencies": { "rollup": "^2.60.2", "eslint": "^8.5.0", "react": "^16.0.0", "react-dom": "^16.0.0" } }
这里要注意的点:
version
遵循 semver 语义化版本(验证小工具),格式一般为 {major}.{minor}.{patch}
  • major:大功能/特性更新、对用户使用方式有影响
  • minor:新功能、对用户使用方式无影响
  • patch:bug 修复/不影响用户
我们来看几个易错的例子:
  • 发 alpha/beta 版,1.0.1 版本已发布,发下一个 beta 版:
    • ❌ 发 1.0.1-beta.1
    • ✅ 发 1.0.2-beta.1
  • ^0.x.y 版本匹配问题。例如:用户配置 "^0.9.0",匹配不了 0.10.0 版本(如下图)。建议正式版从 1.x 开始发版。
notion image
 
 
dependencies, devDependencies, peerDependencies
模块包的依赖,很多模块开发者容易写错的地方。这里用 生产者 表示 模块包开发者,消费者 表示使用模块包的应用
  • dependencies运行时依赖,模块消费者会安装这里的依赖。不推荐的配置:
    • ❌ "webpack": "^5.0.0",消费者会安装 webpack,除非这个模块包揽 webpack 功能不需要应用安装
    • ❌ "react": "^17.0.0",消费者安装 react 依赖,可能带来 React 多实例问题
  • devDependencies开发时依赖,消费者不会安装,只为生产者服务。例如:
    • ✅ "rollup": "^2.60.2"
    • ✅ "webpack": "^5.0.0"
    • ✅ "react": "^17.0.0"
  • peerDependencies宿主依赖,指定了当前模块包在使用前需要安装的依赖,这个配置争议比较大,npm 7 后会默认自动安装依赖,而 pnpm、yarn 目前不会。
    • ✅ "react": "^16.0.0 || ^17.0.0"
private
不发布的包,记得设置为 true,避免误操作 npm publish 发到外网造成安全问题。
# packages/private/package.json { "private": true } $ npm publish npm ERR! code EPRIVATE npm ERR! This package has been marked as private npm ERR! Remove the 'private' field from the package.json to publish it.

模块类型

声明当前包属于哪种模块格式(cjs、esm),不同条件加载不同的模块类型,类型的配置字段源于:
单入口(main, module, browser)
如果是单入口包,始终从包名导出 import from 'your-lib',可以按如下配置:
{ // -----单入口---- // 入口文件(使用 cjs 规范) "main": "lib/index.js", // 入口文件(使用 esm 规范) "module": "es/index.js", // 包类型导出 "typings": "typings/index.d.ts", // 浏览器入口 "browser": "dist/index.js", "sideEffects": false }
参数说明:
  • main:cjs 格式的入口文件
  • module:esm 格式的入口文件
  • browser:浏览器端使用,配置成 umd 格式(webpack < 5 会优先使用 browser
  • sideEffects:副作用配置,主要用在 Tree Shaking 场景,设置成 false 则告诉打包工具大胆进行 Tree Shaking。
多入口(exports, browser)
多入口包,例如 import from 'your-lib/react'import from 'your-lib/vue',推荐配置:
{ // ----多入口--- "exports": { "./react": { "import": "dist/react/index.js", "require": "dist/react/index.cjs" }, "./vue": { "import": "dist/vue/index.js", "require": "dist/vue/index.cjs" } }, "browser": { "./react": "dist/react/index.js", "./vue": "dist/vue/index.js" }, "sideEffects": false }
参数说明:
  • exports:Node.js 提出的模块导出提案,好处是可以定义导出的模块路径,支持不同环境(Node.js、浏览器等)下使用不同格式(esm、cjs)的包
  • browsersideEffects 含义同上
 

 
对 package.json 了解后,开始从常见的模块包看下如何进行设计。

怎样设计模块包?

初始化一个 Monorepo 示例项目(包含 apps 和 packages),目录结构如下(其中 apps 包含常见的应用类型):
apps(前端、后端) - deno-app - next-app - node-app - react-app - umi-app - vite-app - vite-react-app packages(模块包) - shared(共享配置模块) - configs - tsconfig.base.json - types - utils - index.ts - package.json - ui(组件库) - react - vue - package.json - native(Rust/C++ 原生模块编译成 npm,用在 Node.js) - src - lib.rs - package.json .npmrc package.json pnpm-workspace.yaml
每个模块包的设计按照下面的步骤展开介绍:
  1. 应用中如何使用?
  1. 怎么构建?
  1. 怎么配 package.json
  1. 效果展示

共享配置模块(packages/shared)

现在要解决枚举、配置、工具方法的复用,希望同时在所有项目中可使用
使用方式
应用中的使用如下:
  1. 项目中声明模块的依赖,workspace:* 表示使用当前 Monorepo 的 shared 模块包
// apps/*/package.json { "dependencies": { "@infras/shared": "workspace:*" } }
为了更方便地调试 Monorepo 包模块,这里我们使用 pnpm workspace 协议(同时 yarn 也支持了这一协议)。
  1. 在项目中使用 import 引 esm 格式、require 引 cjs 格式、常用的项目配置 tsconfig.json
// apps/*/index.{ts,tsx,jsx} import { AppType } from '@infras/shared/types'; import { sum } from '@infras/shared/utils'; console.log(AppType.Web); // 1 console.log(sum(1, 1)); // 2 // apps/*/index.js const { AppType } = require('@infras/shared/types'); const { sum } = require('@infras/shared/utils'); // apps/*/tsconfig.json { "extends": "@infras/shared/configs/tsconfig.base.json" }
构建出 esm、cjs 格式
上文讲到过,我们最后同时打出 esm 和 cjs 格式的包,这样使用方可以按需取用。那么,我们应该用哪个构建工具呢?
这里可选的编译/打包工具:
  • Transformer(编译):babeljs、TypeScript、esbuild
  • Bundler(打包):Rollup、esbuild、webpack、tsup、unbuild
两者区别:编译(a → a'、b → b')、打包(ab → c,All in One)
经过实践,这里选择 tsup,可以快速的、方便的、开箱即用的构建出 esm、cjs 格式的包,同时还有类型。
用 tsup 不用 tsc/rollup/babel 的原因:共享配置模块其实只需要 tsc 就可以解决,用不上 rollup 丰富的生态,工具配置多又麻烦。还有一点是编译打包速度上 tsup 更快。
打包配置 tsup.config.ts 如下:
// packages/shared/tsup.config.ts import { defineConfig } from 'tsup'; export default defineConfig({ entry: ['utils/index.ts', "types/index.ts"], clean: true, dts: true, outDir: "dist", format: ['cjs', 'esm'] });
执行下 tsup 会生成 dist 目录,结构如下:
# packages/shared - dist - utils - index.js(cjs) - index.mjs(esm) - types - index.js - index.mjs - utils - types - package.json
注:不将多入口 utilstypes 目录放到 src 目的是为了在 Monorepo 项目中有更好的 TS 类型支持!实际是用了障眼法,将类型提示指向源文件 ts,真正使用的是 dist 产物目录,比如:
 
package.json
通用模块包的 package.json 如下,因为是多入口,这里用 exportsbrowser的组合导出了 cjs 和 esm 格式包。
// packages/shared/package.json { "name": "@infras/shared", "version": "0.0.1", "description": "An infrastructure monorepo shared library for all projects and apps.", "browser": { "./types": "./dist/types/index.mjs", "./utils": "./dist/utils/index.mjs" }, "exports": { "./types": { "import": "./dist/types/index.mjs", "require": "./dist/types/index.js" }, "./utils": { "import": "./dist/utils/index.mjs", "require": "./dist/utils/index.js" } }, "scripts": { "prepare": "npm run build", "dev": "tsup --watch", "build": "tsup" }, "devDependencies": { "tsup": "^5.10.3" } }
  • scripts.prepare:给模块包加上 prepare 构建脚本后,执行的时机包括:
    • 发布前编译(相当于 prepublishOnly
    • 本地 npm install 会执行(不同于 postinstall 在任何时候 install 都会执行,会造成消费者 install 时 tsup 依赖不存在报错)
同时在使用 pnpm publish 发包的时候会移除 scripts.prepare源码实现
notion image
运行
在前端项目中使用:pnpm start --filter "react-app"
notion image
 
在 Node.js 项目中使用 pnpm start --filter "node-app"
notion image
 
Vite 中使用 pnpm start --filter "vite-app"
notion image
 

组件库 UI 模块(packages/ui)

在 Monorepo 微前端组织架构下,组件库复用的场景可以有效提升研发效率。
使用方式
应用/项目引入方式如下:
  1. 项目中声明模块的依赖,workspace:* 表示使用当前 Monorepo 的 ui 模块包,若不是 Vite 应用需要配置下 dependenciesMeta['@infras/ui'].injected: true
// apps/*/package.json { "dependencies": { "@infras/ui": "workspace:*" }, // 非 Vite 应用 "dependenciesMeta": { "@infras/ui": { "injected": true } } }
dependenciesMeta 起因
这里有 dependenciesMeta 配置非常有意思,源于 pnpm(≥ 6.20)用来解决 Monorepo 下 React 多版本实例导致的 Invalid hook call 问题。
notion image
问题的原因在于:UI 组件库 devDependencies 中的 React 版本和 应用 中的 React 版本不一致,如下引用结构,应用使用的是 [email protected],而组件库使用的是 [email protected]。(issues:react#13991pnpm#3558rushstack#2820组件多实例问题 等):
-- react-app | |- [email protected] |- @infras/ui | |- [email protected] <- devDependencies
在此之前,要解决这个问题,之前有两种方案:
 
而 pnpm 6.20 后推出的 dependenciesMeta ,实际上是 UI 组件库包硬链到应用里,解决 react 组件库本地开发和 peerDependencies 的问题:
apps node_modules @infras/ui - node_modules
  1. 前端使用:分别在 React、Vue 项目中引入组件库
// React 应用: apps/*/index.{ts,tsx,jsx} import { Component } from '@infras/ui/react'; <Component /> // Vue 应用: apps/*/index.vue <script setup lang="ts"> import { Component } from '@infras/ui/vue'; </script> <template> <Component /> </template>
对于不同前端框架的组件,不建议从一个入口导出(即 import { ReactC, VueC } from 'ui'),这样会给应用的按需编译带来很大的麻烦!
  1. 组件服务端渲染
// apps/node-app/index.js const { Component } = require('@infras/ui/react'); const React = require('react'); const ReactDOMServer = require('react-dom/server'); console.log('SSR: ', ReactDOMServer.renderToString(React.createElement(Component)));
 
为了同时构建 React、Vue 组件库模块,包目录设计大致如下:
# packages/ui - react - Component.tsx - index.ts - vue - Component.vue - index.ts - package.json
构建出 esm、cjs、umd
问个小问题:一般大型组件库需要构建出 cjs 格式,面向场景是什么?
选择 Rollup 来同时打包 React、Vue 组件库,需要有几点注意:
  • 配置包格式为 esmcjsumd
  • external 掉 react、react-dom、vue,组件库不建议将框架 React、Vue 打包进去
rollup 配置如下:
// packages/ui/rollup.config.js import { defineConfig } from 'rollup'; ... export default defineConfig([ { input: 'react/index.tsx', external: ['react', 'react-dom'], plugins: [...], output: [ { name, file: './dist/react/index.js', format: 'umd', globals: { react: 'React', 'react-dom': 'ReactDOM' } }, { name, file: './es/react/index.js', format: 'es', }, { name, file: './lib/react/index.cjs', format: 'commonjs', } ] }, { input: 'vue/index.ts', external: ['vue'], plugins: [...], output: [ { name, file: './dist/vue/index.js', format: 'umd', globals: { vue: 'vue', } }, { name, file: './es/vue/index.js', format: 'es', }, { name, file: './lib/vue/index.cjs', format: 'commonjs', } ] } ])
执行 rollup --config rollup.config.js 后,就会生成 disteslib目录:
# packages/ui - dist - react - vue - es - react - vue - lib - react - vue - react - vue - package.json
package.json
组件库的 package.json 同样是多入口,和通用模块一样使用 exports 的组合导出了 cjs、esm、umd 格式包。
{ "name": "@infras/ui", "version": "1.0.0", "description": "An infrastructure monorepo ui library for all front-end apps.", "browser": { "./react": "./es/react/index.js", "./vue": "./es/vue/index.js" }, "exports": { "./react": { "import": "./es/react/index.js", "require": "./lib/react/index.cjs", "default": "./dist/react/index.js" }, "./vue": { "import": "./es/vue/index.js", "require": "./lib/vue/index.cjs", "default": "./dist/vue/index.js" } }, "scripts": { "start": "npm run dev", "dev": "rollup --config rollup.config.js --watch", "build": "rollup --config rollup.config.js", "prepare": "npm run build", "prepublishOnly": "npm run build" }, "peerDependencies": { "react": "^16.0.0 || ^17.0.0", "react-dom": "^16.0.0 || ^17.0.0", "vue": "^3.0.0" }, "devDependencies": { "typescript": "^4.5.2", "@babel/...": "", "rollup/...": "^2.60.2" } }
组件库在 package.json 声明有一点特别注意
  • 组件库增加 browser 配置,不然在 webpack ≤ 4 会出现 Module not found: Error: Can't resolve '模块名' 的报错
{ + "browser": { + "./react": "./es/react/index.js", + "./vue": "./es/vue/index.js" + }, }
原因:Webpack 5 以下不支持 exports 配置 webpack#9509。 Webpack 4 优先走 browser,而 Webpack 5 优先走 exports
 
运行
启动 React 应用(pnpm start --filter "react-app"):
notion image
启动 Vue 应用(pnpm start --filter "vite-app"):
notion image
服务端渲染(pnpm start --filter "node-app"):
notion image

原生语言模块(packages/native)

有趣的是,我们可以在 Monorepo 中使用 Rust / Golang 编写的 npm 包模块,处理一些 CPU 密集型任务。
使用方式
在 Node.js 应用的使用方式如下:
  1. 项目中声明原生语言模块的依赖
// apps/node-app/package.json { "dependencies": { "@infras/rs": "workspace:*" } }
  1. Node.js 中调用:
// apps/node-app/index.js const { sum } = require('@infras/rs'); console.log('Rust \`sum(1, 1)\`:', sum(1, 1)); // 2 // apps/node-app/index.mjs import { sum } from '@infras/rs';
构建出 cjs
这里使用 napi-rs 初始化一个 Rust 构建的 npm 模块包,napi-rs 并没有构建出 esm 格式的包,而是选择用 cjs 格式来兼容 esm(相关 node#40541
# packages/rs - src - lib.rs - npm - index.js - index.d.ts - package.json - Cargo.toml
package.json
直接使用 napi-rs 初始化出来的 package.json,无须进行修改即可使用。
{ "name": "@infras/rs", "version": "0.0.0", "type": "commonjs", "main": "index.js", "types": "index.d.ts", "devDependencies": { "@napi-rs/cli": "^2.0.0" }, "scripts": { "prepare": "npm run build", "artifacts": "napi artifacts", "build": "napi build --platform --release", "build:debug": "napi build --platform", "version": "napi version" } }
运行
Node 项目中 pnpm start --filter "node-app",这样看 Rust 编译后的函数执行效率比 Node.js 原生快不少(8.44ms0.069ms
notion image
 

总结

读到这里,想必大家对模块标准有一定的了解,知道一些常见场景下如何进行模块设计,这里做个总结:
  • ESM First:无论什么模块,优先构建出 ESM 格式。多入口包使用 exportsbrowser(若 webpack < 5),单入口使用 mainmodule 可处理大部分模块格式问题
  • 共享配置模块(utils、类型、枚举等)使用 tsup 打包工具,生成 esm、cjs 两种包类型。
  • 组件库通常使用 rollup 打包,生成 esm、cjs、umd 三种包类型,同时要注意 React 组件库在版本不一致时的多实例问题
演示的 Monorepo 应用在线预览如下:

参考


© ycjcl868 2021 - 2022