能力简介

在 coding 过程中，我们经常需要点击跳转，查看定义。而在 monorepo 多项目开发时，包源码位于同一仓库，直接跳转到源码查看或许是更好的选择。

基于这个目的，我们发现 TS 在 3.0 版本之后支持了 特性，下面是一份示例配置：

{
  "compilerOptions": {}, // The usual
  "references": [
    { "path": "../projects/a" }
  ]
}

Project References 允许我们将 TS 项目分割成若干个模块，彼此独立，与 monorepo 的使用场景，目的类似。当我们将项目彼此关联起来之后，在 TypeScript 层面，将会有以下效果：

1. 【开发】互相链接的项目会构成一个整体，无需构建产物，可直接跳转到源码，非常便利。
2. 【校验】在 Build 模式 (tsc --build)下，会按照依赖关系自动构建引用链中的所有项目。

该功能对于开发和校验都有着积极意义，特别是第一点，对于开发体验的提升是非常大的。我们可以通过 vscode 内置的 TS Language Server 语言服务，直接跳转到源码。

但在此之前，我们还有一些配置需要完善，才能确保 Project References 正确开启。

开启 composite

开启 Project references 的项目需要同时设置 compilerOptions.composite 为 true。以确保 TS 能够快速找到引用项目的「输出内容」。启用后：

• rootDir 需要设置到源码目录，否则可能会影响源码加载，通常设置为 src

• 项目文件必须包含在 include 或 files 配置中，若引用文件不包含在内，tsc 构建时会抛出错误

• declaration 选项必须开启

上面👆提到的「输出内容」指，TS 如何从一个引用项目中找到源码，举个栗子🌰：

假设我们在 <root>projects/a 目录下有一个项目，名为 @project/a，在 monorepo 中还有另一个项目 b

import { xxx } "@project/a"; // 尝试从 a 项目中导入变量

当我们配置了 references 后

import { xxx } "<root>/projects/a"; // 配置了 references 的效果，但缺少 src 层级

进一步配置 rootDir 之后

import { xxx } "<root>/projects/a/src"; // ✅ 配置 rootDir: "src" 后正确加载到了源码

此时，当我们在 b 项目中尝试点击 xxx 变量定义的时候，tsserver 会帮忙直接跳转到 a 项目的的源码位置。

效果展示

配置 Project References 之后直接跳转源码

不配置则跳转产物