Project References

TypeScript

Project references 是 TS 3.0 新特性，可以将 ts 程序分成更小的部分，从而提升构建性能，加强组件间的逻辑分离。

tsc 命令的 --build 参数配合 project refernces 可以使构建更快。

介绍

tsconfig.json 顶层属性 references 是一个对象数组，指定了参考的项目：

{
    "compilerOptions": {
        // the usual
    },
    "references": [
        { "path": "../src" }
    ]
}

每个 path 属性都指向一个包含 tsconfig.json 或包含它的文件夹，结果是：

• 导入 referenced 项目的模块时，这个项目 output 的 .d.ts 文件会替代导入
• 如果 referenced 的项目构建生成的是一个 outFile，当前项目会可见它的 .d.ts
• --build 模式会自动在有需要的时候构建 referenced 项目（如果不开启则不会自动构建）

可以避免多个项目开发时的多次编译和类型检查，减少内存使用。

composite

referenced 的项目必须启用 compilerOptions.composite，并遵守 composite 的三个约束（rootDir、include、declaration）

declarationMap

referenced 的项目可以启用 declarationMap 来支持编辑器的跳转到源码位置

Build 模式

tsc 的 --build 或 -b 参数可以增量构建，作用是：

• 找到所有 referenced 的项目

• 检测这些项目是否是最新的

• 自动按照依赖顺序构建过期的项目

tsc -b
tsc -b src
tsc -b foo/prd.tsconfig.json bar

传给 -b 的文件顺序 ts 会自动整理

支持的参数

• --dry：只打印结果而不执行

• --clean：删除指定项目的 outputs

• --force：强制构建所有项目（强行过期）

• --watch：watch 模式，通常结合 --verbose

• --verbose：打印log

Caveats

tsc 默认关闭 noEmitOnError，即使有语法或者类型错误也会构建 .js 和 .d.ts 文件，但在增量构建模式下错误只会出现一次（因为后续构建可能会跳过这部分），所以 tsc -b 最好为所有项目开启 noEmitOnError

如果使用某些不保留源文件时间戳的修改工具，需要手动运行 --force 来构建

最佳实践

在指定项目的 reference 文件时建议使用一个单独的 solution 配置文件来管理当前项目的所有叶子节点项目，通过 extends 使用，并把 files 字段设置成空数组即可避免重复编译：

{
    "references": [
        { "path": "pathToNode1" },
        { "path": "pathToNode2" },
        // ...
    ],
    "files": []
}