monorepo 发布库 --- 打包文件
目录
esm & cjs
使用 tsup 进行打包
安装使用
多个入口点
捆绑格式
监视模式
生成声明文件
设置构建脚本
设置 dev 脚本
使用合适的工具，从 monorepo 发布包到 npm 注册表可以是一个顺畅的体验。
虽然本指南无法解决稳健包所需的所有可能的编译、打包和发布配置，但它将解释一些基础知识。
如果你想将 monorepo 的一些包发布到 npm，你应该遵循此设置。 如果你不需要发布到 npm，你应该使用内部代替。 它们更容易设置和使用。
esm & cjs
与内部包不同，外部包可以部署到 npm并且在本地使用。 在本指南中，我们将把一个包打包成 ECMAScript 模块 (esm) 和 CommonJS 模块 (cjs) 两种格式，它们是 npm 上最常用的格式。
| 特性 | ECMAScript 模块 (ESM) | CommonJS (CJS) |
|---|---|---|
| 来源 | ECMAScript 标准 (ES6+) | Node.js 社区规范 (非官方标准) |
| 语法 | import / export | require() / module.exports 或 exports |
| 加载时机 | 静态加载 （编译时解析依赖，提升效率） | 动态加载 （运行时解析依赖，更灵活） |
| 加载方式 | 异步（浏览器原生支持，Node.js 中可并行加载） | 同步（Node.js 中阻塞执行） |
| 运行环境 | 现代浏览器、Node.js（需配置或 .mjs 扩展名） | Node.js 默认（传统环境）、浏览器需打包工具转换 |
| 模块对象 | 严格模式（默认） 无 this、arguments 等全局注入 | 非严格模式（默认） 含 require、module 等 |
| Tree Shaking | ✅ 支持（静态结构利于打包工具优化） | ❌ 难优化（动态依赖难以静态分析） |
| 循环引用处理 | 输出值的引用（实时绑定） | 输出值的拷贝（可能不完整） |
| 文件扩展名 | .mjs 或 .js（package.json 中设置 "type": "module"） | .cjs 或 .js（默认） |
ESM： 浏览器项目、新 Node.js 项目、需要 Tree Shaking 的前端工程。
CJS： 旧 Node.js 项目、未支持 ESM 的 npm 包。
使用 tsup 进行打包
tsup 是一个基于 ESBuild 实现在零配置的情况下快速打包 Typescript 模块的库，支持 .ts、.tsx的转换。它基于esbuild，但是同时也选择融合其他的构建工具共同参与，弥补了esbuild的不足。
安装使用
# pnpm 安装 同样也可以npm yarn 等
pnpm add tsup -D
packages.json 文件中声明
{"build":"tsup"
}简单使用可以在命令后面加输出路径等 也可以添加配置文件去使用
文件被写入
./dist您可以一次捆绑多个文件：这将输出dist/index.js和dist/cli.js。
{"build":"tsup src/index.ts src/cli.ts"
}也可以使用配置文件，根目录下面新建一个 tsup.config.ts 文件
import { defineConfig } from 'tsup'export default defineConfig({entry: ['./src/index.ts'], // 打包入口splitting: false,sourcemap: true,clean: true,
})您还可以使用标志指定自定义文件名--config，或传递--no-config以禁用配置文件。
"scripts": {"build": "tsup --format esm,cjs,iife --config tsup.config.ts"
},多个入口点
除了使用位置参数tsup [...files]指定多个入口点之外，还可以使用 cli 标志--entry：
# Outputs `dist/a.js` and `dist/b.js`.
tsup --entry src/a.ts --entry src/b.ts
相关的输出文件名可以定义如下：
# Outputs `dist/foo.js` and `dist/bar.js`.
tsup --entry.foo src/a.ts --entry.bar src/b.ts
它相当于以下内容tsup.config.ts：
export default defineConfig({// Outputs `dist/a.js` and `dist/b.js`.entry: ['src/a.ts', 'src/b.ts'],// Outputs `dist/foo.js` and `dist/bar.js`entry: {foo: 'src/a.ts',bar: 'src/b.ts',},
})
捆绑格式
支持的格式：esm、、cjs（默认）和iife。
您可以一次性捆绑多种格式：
tsup src/index.ts --format esm,cjs,iife
这将输出以下文件夹结构中的文件：
dist
├── index.mjs # esm
├── index.global.js # iife
└── index.js # cjs
如果type您的字段package.json设置为module，文件名会略有不同：
dist
├── index.js # esm
├── index.global.js # iife
└── index.cjs # cjs
阅读有关esmNode.js 中的支持的更多信息。
如果您不想要像.mjs或这样的扩展.cjs，例如您希望您的库在不支持这些扩展的捆绑器（或环境）中使用，您可以启用--legacy-output标志：
tsup src/index.ts --format esm,cjs,iife --legacy-output
..输出为：
dist
├── esm
│ └── index.js
├── iife
│ └── index.js
└── index.js
监视模式
tsup src/index.ts --watch
开启监视模式。这意味着在初始构建之后，tsup 将继续监视任何已解析文件中的更改。
默认情况下它总是忽略dist, node_modules&.git
tsup src/index.ts --watch --ignore-watch ignore-this-folder-too
您可以指定多个文件夹重复“--ignore-watch”，例如：tsup src src/index.ts --watch --ignore-watch folder1 --ignore-watch folder2
生成声明文件
tsup index.ts --dts
这将生成./dist/index.js和./dist/index.d.ts。当生成多种bundle 格式时，每种 bundle 格式都会生成一个声明文件。这对于使用者使用 TypeScript 进行准确的类型检查是必需的。请注意，使用 以外的任何工具生成的声明文件都tsc不能保证没有错误，因此最好在发布之前使用或@arethetypeswrong/clitsc等工具测试输出。
如果您有多个条目文件，则每个条目都会有一个对应的.d.ts文件。因此，当您只想为单个条目生成声明文件时，请使用--dts <entry>以下格式，例如--dts src/index.ts。
请注意，--dts不会解析文件中使用的外部（又名node_modules）类型.d.ts，如果这是某种要求，请尝试使用实验--dts-resolve标志。
设置构建脚本
让我们从使用内部包教程创建的包开始。
在那里，我们创建了一个 @repo/math 包，其中包含一些用于加法和减法数字的辅助函数。 我们已经决定这个包足够好用在 npm 上，所以我们将对其进行打包。
我们将使用打包器为 @repo/math 添加一个 build 脚本。 如果你不确定选择哪个，我们推荐 tsup。
使用你的包管理器在 ./packages/math 包内安装 tsup，然后为其创建一个构建脚本
{"scripts": {"build": "tsup src/index.ts --format cjs,esm --dts"}
}tsup 默认将文件输出到 dist 目录，因此你应该
将 dist 添加到你的 .gitignore 文件中，以确保它们不会被提交到源代码控制。
将 dist 添加到你的 turbo.json 中 build 的输出。
{"tasks": {"build": {"outputs": ["dist/**"]}}
}这样，当 tsup 运行时，输出可以被 Turborepo 缓存。
最后，我们应该更新我们的包入口点。 在 package.json 内部，将使用 CommonJS 模块 (cjs) 的客户端的 main 指向 ./dist/index.js，将使用 ECMAScript 模块 (esm) 的客户端的 module 指向 ./dist/index.mjs，并将 types 指向类型定义文件 - ./dist/index.d.ts
{"main": "./dist/index.js", #cjs"module": "./dist/index.mjs", #esm"types": "./dist/index.d.ts" #d.ts
}不需要同时打包到 cjs 和 esm。 但是，建议这样做，因为它允许你的包在更广泛的环境中使用。如果你在使用 main、module 和 types 时遇到错误，请查看 tsup 文档。打包是一个复杂的主题，我们这里没有空间涵盖所有内容！
这里作者的type=module 所以使用了exports 可以参考一下这个配置
"exports": {".": {"require": "./dist/index.cjs","import": "./dist/index.js"},"./platform": {"require": "./dist/platform.cjs","import": "./dist/platform.js"}
在我们的应用程序之前构建我们的包
在我们运行 turbo run build 之前，我们需要考虑一件事。 我们刚刚在我们的 monorepo 中添加了一个任务依赖。 packages/math 的 build 需要在 apps/web 的 build之前运行。
幸运的是，我们可以使用 dependsOn 轻松配置它。
{"tasks": {"build": {"dependsOn": ["^build"]}}
}现在，我们可以运行 turbo run build，它会自动在构建我们的应用程序之前构建我们的包。
设置 dev 脚本
我们的设置存在一个小问题。 我们构建我们的包很好，但它在开发中效果不佳。 我们对 @repo/math 包所做的更改没有反映在我们的应用程序中。
那是因为我们没有一个 dev 脚本来在我们工作时重建我们的包。 我们可以轻松添加一个
{"scripts": {"build": "tsup src/index.ts --format cjs,esm --dts","dev": "tsup src/index.ts --format cjs,esm --dts --watch"}
}作者没有用ts可以这样 去掉 dts选项
"scripts": {"build": "tsup src/index.js src/platform.js --format cjs,esm","dev": "tsup src/index.js src/platform.js --format cjs,esm --watch"},这会将 --watch 标志传递给 tsup，这意味着它将监视文件更改。
如果我们在 turbo.json 中已经设置了dev 脚本，运行 turbo run dev 将并行运行我们的 packages/math dev 任务和我们的 apps/web dev 任务。