[译] TSConfig 配置文件速查表

小弟调调

发布于 2023-09-20 08:07:59

3830

发布于 2023-09-20 08:07:59

文章被收录于专栏：埋名埋名

TSConfig 配置文件速查表 The TSConfig Cheat Sheet

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: 只想要代码？请看下面：

{   "compilerOptions": {     /* Base Options: */     /* 基本选项: */     "esModuleInterop": true,     "skipLibCheck": true,     "target": "es2022",     "verbatimModuleSyntax": true,     "allowJs": true,     "resolveJsonModule": true,     "moduleDetection": "force",     /* Strictness */     /* 严格性: */     "strict": true,     "noUncheckedIndexedAccess": true,     /* If transpiling with TypeScript: */     /* 如果使用 TypeScript 进行转译: */     "moduleResolution": "NodeNext",     "module": "NodeNext",     /* If NOT transpiling with TypeScript: */     /* 如果不使用 TypeScript 进行转译: */     "moduleResolution": "Bundler",     "module": "ESNext",     "noEmit": true,     /* If your code runs in the DOM: */     /* 如果代码在 DOM 中运行: */     "lib": ["es2022", "dom", "dom.iterable"],     /* If your code doesn't run in the DOM: */     /* 如果代码不在 DOM 中运行: */     "lib": ["es2022"],     /* If you're building for a library: */     /* 如果你正在构建一个库: */     "declaration": true,     /* If you're building for a library in a monorepo: */     /* 如果你正在构建一个位于单体库中的库: */     "composite": true,     "sourceMap": true,     "declarationMap": true   } }

Full Explanation 完整解释

Base Options 基本选项

Here are the base options I recommend for all projects. 这里是我建议所有项目使用的基本选项。

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

esModuleInterop: Helps mend a few of the fences between CommonJS and ES Modules.
esModuleInterop：有助于修复 CommonJS 和 ES Modules 之间的一些问题。
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，以获得更稳定的支持。
verbatimModuleSyntax: With this option, only imports using import type will be removed. This is the most predictable behavior.
verbatimModuleSyntax：使用此选项，只有使用 import type 导入的内容才会被移除。这是最可预测的行为。
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 将所有文件视为模块。这有助于避免 "cannot redeclare block-scoped variable" 错误。

严格性 Strictness

这里是我建议所有项目使用的严格性选项。 Here are the strictness options I recommend for all projects.

{   "compilerOptions": {     "strict": true,     "noUncheckedIndexedAccess": 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：防止在访问数组或对象之前未先检查其是否定义。这是防止运行时错误的一个很好的方法，应该包含在严格模式中。

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 文件），你将需要以下选项。

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

moduleResolution: Tells TypeScript how to resolve modules. NodeNext is the best option for if the code you're writing is meant to be run in Node.
moduleResolution：告诉 TypeScript 如何解析模块。对于要在 Node 中运行的代码，NodeNext 是最佳选项。
module: Tells TypeScript what module syntax to use. NodeNext is the best option for Node.
module：告诉 TypeScript 使用哪种模块语法。对于 Node，NodeNext 是最佳选项。

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 作为一种更多用于代码检查的工具，你将需要以下选项。

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

moduleResolution: Bundler is the best option for if the code you're writing is meant to be bundled with a tool like Webpack, Rollup, Babel, SWC, or ESBuild.
moduleResolution：对于要使用工具（如 Webpack、Rollup、Babel、SWC 或 ESBuild）进行打包的代码，Bundler 是最佳选项。
module: ESNext is the best option because it most closely mimics how bundlers treat modules.
module：ESNext 是最佳选项，因为它最接近打包工具对模块的处理方式。

Running in the DOM 在 DOM 中运行

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

{   "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"]。

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

These are the same as above, but without the dom and dom.iterable typings. 这与上面的选项相同，但不包括 dom 和 dom.iterable 类型定义。

Building for a Library 构建库

If you're building for a library, you'll want declaration: true. 如果你正在构建一个库，你将需要 declaration: true。

{   "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 在单体库中构建库

If you're building for a library in a monorepo, you'll also want these options. 如果你正在单体库中构建库，你还将需要以下选项。

{   "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 你的项目是单体库的一部分，也帮助它缓存构建以提高速度。
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 生成源映射和声明映射。这些是为了当你的库的使用者进行调试时，他们能够直接跳转到原始源代码。