TSConfig 小抄(翻译)

tsconfig.json 让每个人都感到害怕。这是一个巨大的文件，有大量的潜在选项。

但实际上，你只需要关心几个配置选项。让我们把它们搞清楚，并制作成小抄。

快速开始

只想要代码？给你

{

  "compilerOptions": {

    /* 基础选项: */ 
    "esModuleInterop": true,
    "skipLibCheck": true,
    "target": "es2022",
    "allowJs": true,
    "resolveJsonModule": true,
    "moduleDetection": "force",
    "isolatedModules": true,

    /* 严格性 */ 
    "strict": true,
    "noUncheckedIndexedAccess": true,

    /* 如果转用 TypeScript: */ 
    "moduleResolution": "NodeNext",
    "module": "NodeNext",
    "outDir": "dist",
    "sourceMap": true,

    /* 如果你是为库而建：: */ 
    "declaration": true,
    
    /* 如果你正在为一个 monorepo 中的库建立项目。: */ 
    "composite": true,
    "declarationMap": true,

    /* 如果不使用TypeScript进行转译: */ 
    "moduleResolution": "Bundler",
    "module": "ESNext",

    "noEmit": true,

    /* 如果你的代码在DOM中运行: */ 
    "lib": ["es2022", "dom", "dom.iterable"],

    /* 如果你的代码不在DOM中运行: */ 
    "lib": ["es2022"]
  }

}

充分说明

 基础选项

以下是我为所有项目推荐的基础选项。

{
  "compilerOptions": {
    "esModuleInterop": true,
    "skipLibCheck": true,
    "target": "es2022",
    "allowJs": true,
    "resolveJsonModule": true,
    "moduleDetection": "force",
    "isolatedModules": true
  }
}

• esModuleInterop :有助于修补 CommonJS 和 ES 模块之间的一些分歧。
• skipLibCheck ：跳过检查 .d.ts 文件的类型。这对性能非常重要，因为否则将检查所有 node_modules 文件。
• target ：您使用的 JavaScript 版本。为了稳定起见，我建议使用 es2022 而不是 esnext 。
• allowJs 和 resolveJsonModule ：允许您导入 .js 和 .json 文件。非常有用。
• moduleDetection : 此选项强制 TypeScript 将所有文件视为模块。这有助于避免 "无法重新声明块作用域变量 "的错误。
• isolatedModules ：该选项可防止将模块视为孤立文件时不安全的一些 TS 功能。

严格性

以下是我为所有项目推荐的严格程度选项。

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true
  }
}

• strict : 启用所有严格类型检查选项。不可或缺。
• noUncheckedIndexedAccess ：防止在未检查数组或对象是否已定义的情况下访问该数组或对象。这是防止运行时出错的好方法，因此应将其包含在 strict 中。

许多人推荐tsconfig/bases 中的严格性选项，这是一个很棒的仓库，它对 TSConfig 选项进行了编目。这些选项包括许多我认为过于“嘈杂”的规则，例如 noImplicitReturns、noUnusedLocals、noUnusedLocals 和 noFallthroughCasesInSwitch。 我建议你只在需要时才将这些规则添加到你的 tsconfig.json 中。

使用 TypeScript 进行转译

如果使用 tsc 对代码进行转译（创建 JavaScript 文件），则需要这些选项。

{
  "compilerOptions": {
    "moduleResolution": "NodeNext",
    "module": "NodeNext",
    "outDir": "dist"
  }
}

• moduleResolution : 告诉 TypeScript 如何解析模块。如果您编写的代码要在 Node 中运行， NodeNext 是最佳选择。
• module : 告诉 TypeScript 使用什么模块语法。 NodeNext 是 Node 的最佳选择。
• outDir : 告诉 TypeScript 将编译后的 JavaScript 文件放在哪里。 dist 是我的首选约定，但这取决于你。

建立一个库

如果您要为一个库进行构建，则需要 declaration: true 

{
  "compilerOptions": {
    "declaration": true
  }
}

• declaration : 告诉 TypeScript 输出 .d.ts 文件。这样，库才能在创建的 .js 文件上获得自动完成功能。

在 Monorepo 中建造库

如果您在 monorepo 中为一个库构建，您也需要这些选项。

{
  "compilerOptions": {
    "declaration": true,
    "composite": true,
    "sourceMap": true,
    "declarationMap": true
  }
}

• composite : 告诉 TypeScript 输出 .tsbuildinfo 文件。这将告诉 TypeScript 你的项目是 monorepo 的一部分，并帮助它缓存构建以更快地运行。
• sourceMap 和 declarationMap ：告诉 TypeScript 输出源映射和声明映射。当用户调试库时，他们可以使用 go-to-definition 跳转到原始源代码。

不使用TypeScript进行转译

如果您不使用 tsc 对代码进行转译，即更多地将 TypeScript 用作衬底，则需要这些选项。

{
  "compilerOptions": {
    "moduleResolution": "Bundler",
    "module": "ESNext",
    "noEmit": true
  }
}

• moduleResolution ： Bundler 是最佳选择，如果您编写的代码需要与 Webpack、Rollup、Babel、SWC 或 ESBuild 等工具捆绑使用。
• module : ESNext 是最佳选择，因为它最接近捆绑程序对待模块的方式。

在 DOM 中运行

如果代码在 DOM 中运行，则需要这些选项。

{
  "compilerOptions": {
    "lib": ["es2022", "dom", "dom.iterable"]
  }
}

• lib : 告诉 TypeScript 要包含哪些内置类型。 es2022 是稳定性最好的选项。 dom 和 dom.iterable 为 window 和 document 等提供了类型。

不在 DOM 中运行

如果您的代码不在 DOM 中运行，则需要 lib: ["es2022"] 。

{
  "compilerOptions": {
    "lib": ["es2022"]
  }
}

它们与上述内容相同，但没有 dom 和 dom.iterable 类型。