工作区跨包引用时TS编译器无法识别重映射路径问题

在Bun/Yarn工作区环境下，server包的TypeScript配置如下：

"compilerOptions": {
  "baseUrl": "./src",
  "paths": {
    "~/*": ["*"]
  }
},

在另一个mobile包中，通过"@repo/server": "workspace:*"（Bun）或"@repo/server": "1.0.0"（Yarn）的方式引用server包，执行导入语句：

import { X } from "@repo/server";

在mobile包上运行tsc命令时出现报错：

../server/src/index.ts(1,23): error TS2307: Cannot find module '~/api/something' or its corresponding type declarations.

但单独在server包上运行tsc可以正常编译。

问题原因 #

TypeScript处理跨包依赖时，不会自动继承被依赖包的paths和baseUrl配置。mobile包的TypeScript无法识别server包中自定义的~/*路径别名，导致解析失败。

解决方案 #

方案1：在mobile包中同步路径别名配置 #

修改mobile包的tsconfig.json，添加对应server包的路径映射，注意路径要基于mobile包的位置指向server的src目录：

"compilerOptions": {
  // 保留原有配置...
  "baseUrl": ".",
  "paths": {
    "~/*": ["./../server/src/*"]
  }
}

方案2：编译server包生成完整类型定义（推荐） #

让server包在编译阶段将路径别名替换为实际路径，并生成可被mobile包直接识别的类型文件：

1. 在server包的tsconfig.json中开启类型声明输出：

"compilerOptions": {
  // 保留原有配置...
  "declaration": true,
  "declarationDir": "./dist",
  "outDir": "./dist"
}

2. 在server包的package.json中指定类型入口：

"types": "./dist/index.d.ts",
"main": "./dist/index.js"

3. 编译server包后，mobile包引用编译后的产物而非源码，此时路径别名已被替换为相对路径，不会出现解析问题。

方案3：使用TypeScript复合项目管理工作区 #

通过复合项目（Composite Projects）让TypeScript统一管理工作区的依赖解析：

1. 在工作区根目录创建tsconfig.json：

"compilerOptions": {
  "composite": true,
  "baseUrl": ".",
  "paths": {
    "@repo/*": ["./packages/*/src"]
  }
},
"references": [
  {"path": "./packages/server"},
  {"path": "./packages/mobile"}
]

2. 在server和mobile包的tsconfig.json中添加：

"compilerOptions": {
  // 保留原有配置...
  "composite": true
},
"references": [{"path": "../tsconfig.json"}]

内容的提问来源于stack exchange，提问作者sh03