npm 包输出 es/cjs 产物
在开发一个 npm 包时,通常需要同时输出 ES 模块和 CommonJS 模块的产物供不同的构建进行使用。在只使用tsc
进行产物编译的情况下,我们通常可以通过配置两个独立的 tsconfig.json
配置文件,并在一个 npm script 中 执行两次 tsc 命令来实现
项目结构
假设我们的项目结构如下:
yaml
my-package/
├── src/
│ └── index.ts
├── dist/
│ ├── es/
│ └── cjs/
├── package.json
├── tsconfig.es.json
└── tsconfig.cjs.json
配置 TypeScript
tsconfig.es.json
为 ES 模块创建一个 tsconfig.es.json
文件:
json
{
"compilerOptions": {
"rootDir": "src",
"module": "ESNext",
"moduleResolution": "Node",
"outDir": "dist/es"
},
"include": ["src"]
}
tsconfig.cjs.json
为 CommonJS 模块创建一个 tsconfig.cjs.json
文件:
json
{
"compilerOptions": {
"rootDir": "src",
"module": "CommonJS",
"moduleResolution": "Node",
"outDir": "dist/cjs"
},
"include": ["src"]
}
配置构建脚本
在 package.json 中,我们可以添加以下脚本来构建我们的项目,执行两次 tsc 并分别指定不同的配置文件
json
{
"scripts": {
"build": "tsc -p tsconfig.es.json && tsc -p tsconfig.cjs.json",
}
}
通过运行 npm run build,可以生成同时包含 ES 模块和 CommonJS 模块的产物
TypeScript 的 references 是什么
TypeScript 的项目引用(Project References)是 TypeScript 3.0 引入的一项功能,允许一个 TypeScript 项目引用另一个 TypeScript 项目。这使得我们可以将大型代码库拆分为多个较小的项目,并且这些项目可以相互依赖
Project References 的好处
- 增量编译:当项目引用被正确配置时,TypeScript 只会重新编译发生变化的部分,从而大幅提升编译速度。
- 模块化:通过项目引用,可以将代码库拆分为多个独立的、可复用的模块,提升代码的可维护性和可读性。
- 类型安全:项目引用确保了项目之间的类型安全,避免了类型不一致的问题。
配置
要使用项目引用,需要在 tsconfig.json 中添加 references
字段。例如:
json
{
"compilerOptions": {
"composite": true,
"declaration": true,
"outDir": "./dist"
},
"include": ["src"],
"references": [
{ "path": "../other-project" }
]
}
相应的子项目需要存在相应的tsconfig.json
配置,并且配置compilerOptions.composite=true
,这样才能被主项目引用。如
json
{
"compilerOptions": {
"composite": true,
"types": [],
"rootDir": "src",
"module": "ESNext",
"moduleResolution": "Node",
"outDir": "dist"
}
}
使用 TypeScript 的 references 后如何实现一个命令 tsc 输出 ES 和 CommonJS 产物并且提升增量编译的性能
仍以上面的项目结构为例子,我们使用 TypeScript 的项目引用来实现这个需求。
项目结构
假设我们的项目结构如下:
yml
my-package/
├── src/
│ └── index.ts
├── dist/
│ ├── es/
│ └── cjs/
├── package.json
├── tsconfig.json
├── tsconfig.base.json
├── tsconfig.es.json
└── tsconfig.cjs.json
首先,我们需要在根目录下创建一个 tsconfig.json 文件,用于配置项目引用:
json
{
"files": [],
"references": [
{ "path": "./tsconfig.es.json" },
{ "path": "./tsconfig.cjs.json" }
]
}
配置 tsconfig.es.json
为 ES 模块创建一个 tsconfig.es.json 文件:
json
{
"extends": "./tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist/es",
"module": "ESNext"
}
}
配置 tsconfig.cjs.json
为 CommonJS 模块创建一个 tsconfig.cjs.json 文件:
json
{
"extends": "./tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist/cjs",
"module": "CommonJS"
}
}
公共配置 tsconfig.base.json
为了避免重复配置,我们可以创建一个 tsconfig.base.json 文件,包含通用的配置:
json
{
"compilerOptions": {
"target": "ES5",
"declaration": true,
"moduleResolution": "node",
"esModuleInterop": true,
"skipLibCheck": true,
"composite": true,
"rootDir": "src"
},
"include": ["src"]
}
构建脚本
在 package.json 中,我们可以添加以下脚本来构建我们的项目
json
{
"scripts": {
"build": "tsc -b"
}
}
此时我们不再需要执行两次 tsc 命令,而是只需要执行一次 tsc -b 命令即可输出符合我们需求的 es + cjs 产物(和上面的两次执行 tsc
是一样的效果)。
在这个场景下 TypeScript 会根据项目引用的配置,自动构建 ES 模块和 CommonJS 模块,并且只会重新编译发生变化的部分,从而提升增量编译的性能