Monorepo 下的模块包设计实践

前言

1. 怎样设计一个共享配置包（配置、类型、utils、枚举），同时在前端、Node.js、Vite 等项目中使用

2. UI 组件库怎么打包？组件库怎么支持服务端渲染（SSR）？有哪些好的最佳实践？

3. 怎么使用原生语言（Rust / C++ / Golang 等）编写的模块包？

为什么设计模块包？

• 重复定义问题：工具方法、类型、配置在不同应用之间重复定义，维护困难。（例如：一个应用类型 AppType 的定义可以达 10 多处，很多还是旧的定义；项目用到配置； tsconfig.json 、prettier 等相同的配置写一遍又一遍）

• 依赖管理问题：为解决重用问题，我们也试过将模块先发成 npm 包，但发完需要更新应用 package.json 中的依赖版本，一来一回非常折腾。

• 跨项目使用问题：同构就是指 模块同时跑在前后端项目，兼容不同的模块包规范（CommonJS、ESM 等）。如果没有很好的设计包结构，经常会在项目编译打包时报错 ❌。

有哪些类型的模块包？

• 共享配置模块（跨前后端）：同时打出 ESM、CJS 格式的包（目前 Node.js 运行时对 ESM 支持不是很好）

• UI 组件库：同时打出 ESM、CJS、UMD（umd 主要是为了让前端项目可以做 external，减少构建时长）

• 面向 Node.js 项目：目前只需要打出 CJS 格式

package.json 模块声明

基础信息

// 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"
    }
}

• 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 开始发版。

• 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"

# 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.

模块类型

• npm 规范

• Node.js 官方模块加载规范

• Package Exports

{
    // -----单入口----
    // 入口文件（使用 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": {
        "./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）的包

• browser 和 sideEffects 含义同上

怎样设计模块包？

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. 应用中如何使用？

2. 怎么构建？

3. 怎么配 package.json

4. 效果展示

共享配置模块（packages/shared）

1. 项目中声明模块的依赖，workspace:* 表示使用当前 Monorepo 的 shared 模块包

// apps/*/package.json
{
  "dependencies": {
     "@infras/shared": "workspace:*"
  }
}

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"
}

• Transformer（编译）：babeljs、TypeScript、esbuild

• Bundler（打包）：Rollup、esbuild、webpack、tsup、unbuild

// 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']
});

# packages/shared
- dist
    - utils
        - index.js（cjs）
        - index.mjs（esm）
    - types
        - index.js
        - index.mjs
- utils
- types
- package.json

注：不将多入口 utils、types 目录放到 src 目的是为了在 Monorepo 项目中有更好的 TS 类型支持！实际是用了障眼法，将类型提示指向源文件 ts，真正使用的是 dist 产物目录，比如：

- shared

- dist

- react

- index.js（应用构建加载的入口）

- react

- index.ts（编辑器类型提示的入口）

// 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（源码实现）

组件库 UI 模块（packages/ui）

1. 项目中声明模块的依赖，workspace:* 表示使用当前 Monorepo 的 ui 模块包，若不是 Vite 应用需要配置下 dependenciesMeta['@infras/ui'].injected: true

// apps/*/package.json
{
  "dependencies": {
     "@infras/ui": "workspace:*"
  },
  // 非 Vite 应用
  "dependenciesMeta": {
    "@infras/ui": {
      "injected": true
    }
  }
}

-- react-app
 | |- [email protected]
 |- @infras/ui
 | |- [email protected] <- devDependencies

在此之前，要解决这个问题，之前有两种方案：

• 指定 react 版本，前端应用层在打包构建时，指定具体 react 版本，强制将版本统一。

• 依赖提升，优先使用最新版本的 react，但应用使用版本还是有问题。（pnpm#hoist）

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>

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)));

# packages/ui
- react
    - Component.tsx
    - index.ts
- vue
    - Component.vue
    - index.ts
- package.json

• 配置包格式为 esm、cjs、umd

• external 掉 react、react-dom、vue，组件库不建议将框架 React、Vue 打包进去

// 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',
      }
    ]
  }
])

# packages/ui
- dist
    - react
    - vue
- es
    - react
    - vue
- lib
    - react
    - vue
- react
- vue
- package.json

{
  "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"
  }
}

• 组件库增加 browser 配置，不然在 webpack ≤ 4 会出现 Module not found: Error: Can't resolve '模块名' 的报错

{
+ "browser": {
+   "./react": "./es/react/index.js",
+   "./vue": "./es/vue/index.js"
+ },
}

原生语言模块（packages/native）

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';

# packages/rs
- src
    - lib.rs
- npm
- index.js
- index.d.ts
- package.json
- Cargo.toml

{
  "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"
  }
}

总结

• ESM First：无论什么模块，优先构建出 ESM 格式。多入口包使用 exports 、browser（若 webpack < 5），单入口使用 main、module 可处理大部分模块格式问题

• 共享配置模块（utils、类型、枚举等）使用 tsup 打包工具，生成 esm、cjs 两种包类型。

• 组件库通常使用 rollup 打包，生成 esm、cjs、umd 三种包类型，同时要注意 React 组件库在版本不一致时的多实例问题

• Next.js App

• CRA

• Umi App

• Express App

• Vite Vue 3 App

• Vite React App

• Vue 3 Cli App

参考

• Modules: CommonJS modules | Node.js v14.18.2 Documentation

• ES modules: A cartoon deep-dive – Mozilla Hacks - the Web developer blog

• defense-of-dot-js#proposal

• Node.JS (New) Package.json Exports Field

• JavaScript modules - JavaScript | MDN

• npm Blog Archive: Monorepos and npm

• pnpm monorepo之多组件实例和peerDependencies困境回溯

• jkrems/proposal-pkg-exports

• Import from subfolder of npm package - Tutorial Guruji

• Package.json with multiple entrypoints

• Publish ESM and CJS in a single package

• How to Create a Hybrid NPM Module for ESM and CommonJS.