The TSConfig Cheat Sheet TSConfig 备忘单

tsconfig.json scares everyone. It's a huge file with a TON of potential options.
tsconfig.json 吓到大家了。这是一个巨大的文件，包含大量潜在选项。

But really, there are only a few configuration options you need to care about. Let's figure them out, and cheatsheet them.
但实际上，您只需要关心几个配置选项。让我们弄清楚它们，并制作备忘单。

#

Quickstart 快速开始

Want just the code? Here you go:
只需要代码吗？干得好：

json
{
  "compilerOptions": {
    /* Base Options: */
    "esModuleInterop": true,
    "skipLibCheck": true,
    "target": "es2022",
    "allowJs": true,
    "resolveJsonModule": true,
    "moduleDetection": "force",
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    /* Strictness */
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    /* If transpiling with TypeScript: */
    "module": "NodeNext",
    "outDir": "dist",
    "sourceMap": true,
    /* AND if you're building for a library: */
    "declaration": true,
    /* AND if you're building for a library in a monorepo: */
    "composite": true,
    "declarationMap": true,
    /* If NOT transpiling with TypeScript: */
    "module": "preserve",
    "noEmit": true,
    /* If your code runs in the DOM: */
    "lib": ["es2022", "dom", "dom.iterable"],
    /* If your code doesn't run in the DOM: */
    "lib": ["es2022"]
  }
}

#

Full Explanation 完整说明

#

Base Options 基本选项

Here are the base options I recommend for all projects.
以下是我为所有项目推荐的基本选项。

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

• esModuleInterop: Helps mend a few of the fences between CommonJS and ES Modules.
  esModuleInterop ：帮助修补 CommonJS 和 ES 模块之间的一些界限。
• skipLibCheck: Skips checking the types of .d.ts files. This is important for performance, because otherwise all node_modules will be checked.
  skipLibCheck ：跳过检查 .d.ts 文件的类型。这对于性能很重要，因为否则所有 node_modules 都会被检查。
• target: The version of JavaScript you're targeting. I recommend es2022 over esnext for stability.
  target ：您要定位的 JavaScript 版本。为了稳定性，我推荐 es2022 而不是 esnext 。
• allowJs and resolveJsonModule: Allows you to import .js and .json files. Always useful.
  allowJs 和 resolveJsonModule ：允许您导入 .js 和 .json 文件。总是有用的。
• moduleDetection: This option forces TypeScript to consider all files as modules. This helps to avoid 'cannot redeclare block-scoped variable' errors.
  moduleDetection ：此选项强制 TypeScript 将所有文件视为模块。这有助于避免“无法重新声明块作用域变量”错误。
• isolatedModules: This option prevents a few TS features which are unsafe when treating modules as isolated files.
  isolatedModules ：此选项可防止一些 TS 功能，这些功能在将模块视为独立文件时不安全。
• verbatimModuleSyntax: This option forces you to use import type and export type, leading to more predictable behavior and fewer unnecessary imports. With module: NodeNext, it also enforces you're using the correct import syntax for ESM or CJS.
  verbatimModuleSyntax ：此选项强制您使用 import type 和 export type ，从而导致更可预测的行为并减少不必要的导入。使用 module: NodeNext ，它还强制您使用 ESM 或 CJS 的正确导入语法。

#

Strictness 严格

Here are the strictness options I recommend for all projects.
以下是我为所有项目推荐的严格性选项。

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

• strict: Enables all strict type checking options. Indispensable.
  strict ：启用所有严格类型检查选项。必不可少。
• noUncheckedIndexedAccess: Prevents you from accessing an array or object without first checking if it's defined. This is a great way to prevent runtime errors, and should really be included in strict.
  noUncheckedIndexedAccess ：阻止您在未先检查数组或对象是否已定义的情况下访问该数组或对象。这是防止运行时错误的好方法，确实应该包含在 strict 中。
• noImplicitOverride: Makes the override keyword actually useful in classes.
  noImplicitOverride ：使 override 关键字在类中真正有用。

Many folks recommended the strictness options in tsconfig/bases, a wonderful repo which catalogs TSConfig options. These options include lots of rules which I consider too 'noisy', like noImplicitReturns, noUnusedLocals, noUnusedParameters, and noFallthroughCasesInSwitch. I recommend you add these rules to your tsconfig.json only if you want them.
许多人推荐了 tsconfig/bases 中的严格性选项，这是一个很棒的存储库，其中记录了 TSConfig 选项。这些选项包括许多我认为太“嘈杂”的规则，例如 noImplicitReturns 、 noUnusedLocals 、 noUnusedParameters 和 noFallthroughCasesInSwitch 。我建议您仅在需要时才将这些规则添加到 tsconfig.json 中。

#

Transpiling with TypeScript
使用 TypeScript 进行转译

If you're transpiling your code (creating JavaScript files) with tsc, you'll want these options.
如果您使用 tsc 转译代码（创建 JavaScript 文件），您将需要这些选项。

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

• module: Tells TypeScript what module syntax to use. NodeNext is the best option for Node. moduleResolution: NodeNext is implied from this option.
  module ：告诉 TypeScript 使用什么模块语法。 NodeNext 是 Node 的最佳选择。此选项隐含 moduleResolution: NodeNext 。
• outDir: Tells TypeScript where to put the compiled JavaScript files. dist is my preferred convention, but it's up to you.
  outDir ：告诉 TypeScript 将编译后的 JavaScript 文件放在哪里。 dist 是我的首选约定，但这取决于你。

#

Building for a Library 图书馆建设

If you're building for a library, you'll want declaration: true.
如果您正在构建图书馆，您将需要 declaration: true 。

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

• declaration: Tells TypeScript to emit .d.ts files. This is needed so that libraries can get autocomplete on the .js files you're creating.
  declaration ：告诉 TypeScript 发出 .d.ts 文件。这是必需的，以便库可以自动完成您正在创建的 .js 文件。

#

Building for a Library in a Monorepo
在 Monorepo 中建造图书馆

If you're building for a library in a monorepo, you'll also want these options.
如果您正在 monorepo 中构建库，您还需要这些选项。

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

• composite: Tells TypeScript to emit .tsbuildinfo files. This tells TypeScript that your project is part of a monorepo, and also helps it to cache builds to run faster.
  composite ：告诉 TypeScript 发出 .tsbuildinfo 文件。这告诉 TypeScript 您的项目是 monorepo 的一部分，并且还有助于它缓存构建以加快运行速度。
• sourceMap and declarationMap: Tells TypeScript to emit source maps and declaration maps. These are needed so that when consumers of your libraries are debugging, they can jump to the original source code using go-to-definition.
  sourceMap 和 declarationMap ：告诉 TypeScript 发出源映射和声明映射。需要这些，以便当库的使用者进行调试时，他们可以使用 go-to-definition 跳转到原始源代码。

#

Not Transpiling with TypeScript
不使用 TypeScript 进行转译

If you're not transpiling your code with tsc, i.e. using TypeScript as more of a linter, you'll want these options.
如果您不使用 tsc 转译代码，即使用 TypeScript 作为更多的 linter，您将需要这些选项。

json
{
  "compilerOptions": {
    "module": "preserve",
    "noEmit": true
  }
}

• module: preserve is the best option because it most closely mimics how bundlers treat modules. moduleResolution: Bundler is implied from this option.
  module ： preserve 是最好的选择，因为它最接近地模仿捆绑程序处理模块的方式。此选项隐含 moduleResolution: Bundler 。
• noEmit: Tells TypeScript not to emit any files. This is important when you're using a bundler so you don't emit useless .js files.
  noEmit ：告诉 TypeScript 不要发出任何文件。当您使用捆绑器时，这一点很重要，这样您就不会发出无用的 .js 文件。

#

Running in the DOM 在 DOM 中运行

If your code runs in the DOM, you'll want these options.
如果您的代码在 DOM 中运行，您将需要这些选项。

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

• lib: Tells TypeScript what built-in types to include. es2022 is the best option for stability. dom and dom.iterable give you types for window, document etc.
  lib ：告诉 TypeScript 要包含哪些内置类型。 es2022 是稳定性的最佳选择。 dom 和 dom.iterable 为您提供 window 、 document 等类型。

#

Not Running in the DOM
未在 DOM 中运行

If your code doesn't run in the DOM, you'll want lib: ["es2022"].
如果您的代码不在 DOM 中运行，您将需要 lib: ["es2022"] 。

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

These are the same as above, but without the dom and dom.iterable typings.
这些与上面相同，但没有 dom 和 dom.iterable 类型。

#

Changelog 变更日志

I've been updating this cheatsheet as TypeScript evolves, and as I refine my view of what belongs in a reusable tsconfig.json. Here's the changelog:
随着 TypeScript 的发展，以及我对可重用 tsconfig.json 的看法的完善，我一直在更新这份备忘单。这是变更日志：

• 2024-04-23: Added verbatimModuleSyntax to the base options. With the introduction of module: Preserve, verbatimModuleSyntax is much more useful. Many applications do 'fake ESM', where they write imports and exports but transpile to CommonJS. Next.js is a common example. Before module: Preserve, verbatimModuleSyntax would error on every single import or export statement because it was expecting a module. With module: Preserve, its scope is narrowed making sure import/export type is used correctly.
  2024-04-23：将 verbatimModuleSyntax 添加到基本选项中。随着 module: Preserve 的引入， verbatimModuleSyntax 变得更加有用。许多应用程序都会“伪造 ESM”，即编写导入和导出，但会转译为 CommonJS。 Next.js 是一个常见的示例。在 module: Preserve 之前， verbatimModuleSyntax 在每个导入或导出语句上都会出错，因为它需要一个模块。使用 module: Preserve ，其范围缩小，确保正确使用 import/export type 。
• 2024-04-23: Added noImplicitOverride to the strictness options. Never knew about this option, or the override keyword, until I discovered it while researching my book. noImplicitOverride is a very small improvement at no cost, so why not?
  2024-04-23：在严格选项中添加了 noImplicitOverride 。从来不知道这个选项，或者 override 关键字，直到我在研究我的书时发现它。 noImplicitOverride 是一个非常小的免费改进，所以为什么不呢？

#

What Did I Miss? 我错过了什么？

Hopefully, I've given you a bit of inspiration for the next time you need to configure TypeScript.
希望我能为您下次需要配置 TypeScript 时提供一些灵感。

Did I miss anything? Let me know:
我错过了什么吗？让我知道：

Send Me a Message 给我发一条信息