TypeScript 中的 customConditions

说明 customConditions 如何给 TypeScript 的包导出条件解析追加自定义条件，以及它为什么只在 node16、nodenext、bundler 这类现代解析模式下有效。

#tech / dev #resource / typescript #type / concept #status / growing

[!info] related notes

所属 MOC: TypeScript MOC

配置入口: tsconfig 使用详解

并列概念: TypeScript 中的 moduleResolution, TypeScript 中的 nodenext 与 bundler

一句话定义

customConditions 用来给 TypeScript 在解析 package.json 的 exports / imports 时追加自定义条件名。

官方文档说明，这个选项接收一组额外 conditions。

当 TypeScript 在解析包的：

字段时，它会把这些自定义条件加入默认解析条件集合里。

例如：

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "customConditions": ["my-condition"]
  }
}

那么当目标包的 package.json 中存在：

{
  "exports": {
    ".": {
      "my-condition": "./foo.mjs",
      "import": "./bar.mjs"
    }
  }
}

TypeScript 就会优先考虑 my-condition 对应的分支。

这通常出现在：

官方文档明确写明，它只在这些 moduleResolution 下有效：

paths 更像项目内部的映射；

而 customConditions 更像：

如果项目根本没有用到 exports / imports 条件分支，这个选项通常没有存在感。