Specifies an allowlist of files to include in the program. An error occurs if any of the files can’t be found.

{
  "compilerOptions": {},
  "files": [
    "core.ts",
    "sys.ts",
    "types.ts",
    "scanner.ts",
    "parser.ts",
    "utilities.ts",
    "binder.ts",
    "checker.ts",
    "tsc.ts"
  ]
}

This is useful when you only have a small number of files and don’t need to use a glob to reference many files. If you need that then use include.

The value of extends is a string which contains a path to another configuration file to inherit from. The path may use Node.js style resolution.

The configuration from the base file are loaded first, then overridden by those in the inheriting config file. All relative paths found in the configuration file will be resolved relative to the configuration file they originated in.

It’s worth noting that files, include, and exclude from the inheriting config file overwrite those from the base config file, and that circularity between configuration files is not allowed.

Currently, the only top-level property that is excluded from inheritance is references.

Example

configs/base.json:

{
  "compilerOptions": {
    "noImplicitAny": true,
    "strictNullChecks": true
  }
}

tsconfig.json:

{
  "extends": "./configs/base",
  "files": ["main.ts", "supplemental.ts"]
}

tsconfig.nostrictnull.json:

{
  "extends": "./tsconfig",
  "compilerOptions": {
    "strictNullChecks": false
  }
}

Properties with relative paths found in the configuration file, which aren’t excluded from inheritance, will be resolved relative to the configuration file they originated in.

Specifies an array of filenames or patterns to include in the program. These filenames are resolved relative to the directory containing the tsconfig.json file.

json
{
  "include": ["src/**/*", "tests/**/*"]
}

Which would include:

.
├── scripts                ⨯
│   ├── lint.ts            ⨯
│   ├── update_deps.ts     ⨯
│   └── utils.ts           ⨯
├── src                    ✓
│   ├── client             ✓
│   │    ├── index.ts      ✓
│   │    └── utils.ts      ✓
│   ├── server             ✓
│   │    └── index.ts      ✓
├── tests                  ✓
│   ├── app.test.ts        ✓
│   ├── utils.ts           ✓
│   └── tests.d.ts         ✓
├── package.json
├── tsconfig.json
└── yarn.lock

include and exclude support wildcard characters to make glob patterns:

• * matches zero or more characters (excluding directory separators)
• ? matches any one character (excluding directory separators)
• **/ matches any directory nested to any level

If the last path segment in a pattern does not contain a file extension or wildcard character, then it is treated as a directory, and files with supported extensions inside that directory are included (e.g. .ts, .tsx, and .d.ts by default, with .js and .jsx if allowJs is set to true).

Specifies an array of filenames or patterns that should be skipped when resolving include.

Important: exclude only changes which files are included as a result of the include setting. A file specified by exclude can still become part of your codebase due to an import statement in your code, a types inclusion, a /// <reference directive, or being specified in the files list.

It is not a mechanism that prevents a file from being included in the codebase - it simply changes what the include setting finds.

Project references are a way to structure your TypeScript programs into smaller pieces. Using Project References can greatly improve build and editor interaction times, enforce logical separation between components, and organize your code in new and improved ways.

You can read more about how references works in the Project References section of the handbook

When:

• undefined (default) provide suggestions as warnings to editors
• true unreachable code is ignored
• false raises compiler errors about unreachable code

These warnings are only about code which is provably unreachable due to the use of JavaScript syntax, for example:

ts
function fn(n: number) {
  if (n > 5) {
    return true;
  } else {
    return false;
  }
  return true;
}

With "allowUnreachableCode": false:

ts
function fn(n: number) {
  if (n > 5) {
    return true;
  } else {
    return false;
  }
  return true;
Unreachable code detected.7027Unreachable code detected.
}Try

This does not affect errors on the basis of code which appears to be unreachable due to type analysis.

When:

• undefined (default) provide suggestions as warnings to editors
• true unused labels are ignored
• false raises compiler errors about unused labels

Labels are very rare in JavaScript and typically indicate an attempt to write an object literal:

ts
function verifyAge(age: number) {
  // Forgot 'return' statement
  if (age > 18) {
    verified: true;
Unused label.7028Unused label.
  }
}Try

Ensures that your files are parsed in the ECMAScript strict mode, and emit “use strict” for each source file.

ECMAScript strict mode was introduced in ES5 and provides behavior tweaks to the runtime of the JavaScript engine to improve performance, and makes a set of errors throw instead of silently ignoring them.

With exactOptionalPropertyTypes enabled, TypeScript applies stricter rules around how it handles properties on type or interfaces which have a ? prefix.

For example, this interface declares that there is a property which can be one of two strings: ‘dark’ or ‘light’ or it should not be in the object.

ts
interface UserDefaults {
  // The absence of a value represents 'system'
  colorThemeOverride?: "dark" | "light";
}

Without this flag enabled, there are three values which you can set colorThemeOverride to be: “dark”, “light” and undefined.

Setting the value to undefined will allow most JavaScript runtime checks for the existence to fail, which is effectively falsy. However, this isn’t quite accurate; colorThemeOverride: undefined is not the same as colorThemeOverride not being defined. For example, "colorThemeOverride" in settings would have different behavior with undefined as the key compared to not being defined.

exactOptionalPropertyTypes makes TypeScript truly enforce the definition provided as an optional property:

ts
const settings = getUserSettings();
settings.colorThemeOverride = "dark";
settings.colorThemeOverride = "light";
 
// But not:
settings.colorThemeOverride = undefined;
Type 'undefined' is not assignable to type '"dark" | "light"' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the type of the target.2412Type 'undefined' is not assignable to type '"dark" | "light"' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the type of the target.Try

Report errors for fallthrough cases in switch statements. Ensures that any non-empty case inside a switch statement includes either break, return, or throw. This means you won’t accidentally ship a case fallthrough bug.

ts
const a: number = 6;
 
switch (a) {
  case 0:
Fallthrough case in switch.7029Fallthrough case in switch.
    console.log("even");
  case 1:
    console.log("odd");
    break;
}Try

In some cases where no type annotations are present, TypeScript will fall back to a type of any for a variable when it cannot infer the type.

This can cause some errors to be missed, for example:

ts
function fn(s) {
  // No error?
  console.log(s.subtr(3));
}
fn(42);Try

Turning on noImplicitAny however TypeScript will issue an error whenever it would have inferred any:

ts
function fn(s) {
Parameter 's' implicitly has an 'any' type.7006Parameter 's' implicitly has an 'any' type.
  console.log(s.subtr(3));
}Try

When working with classes which use inheritance, it’s possible for a sub-class to get “out of sync” with the functions it overloads when they are renamed in the base class.

For example, imagine you are modeling a music album syncing system:

ts
class Album {
  download() {
    // Default behavior
  }
}
 
class SharedAlbum extends Album {
  download() {
    // Override to get info from many sources
  }
}Try

Then when you add support for machine-learning generated playlists, you refactor the Album class to have a ‘setup’ function instead:

ts
class Album {
  setup() {
    // Default behavior
  }
}
 
class MLAlbum extends Album {
  setup() {
    // Override to get info from algorithm
  }
}
 
class SharedAlbum extends Album {
  download() {
    // Override to get info from many sources
  }
}Try

In this case, TypeScript has provided no warning that download on SharedAlbum expected to override a function in the base class.

Using noImplicitOverride you can ensure that the sub-classes never go out of sync, by ensuring that functions which override include the keyword override.

The following example has noImplicitOverride enabled, and you can see the error received when override is missing:

ts
class Album {
  setup() {}
}
 
class MLAlbum extends Album {
  override setup() {}
}
 
class SharedAlbum extends Album {
  setup() {}
This member must have an 'override' modifier because it overrides a member in the base class 'Album'.4114This member must have an 'override' modifier because it overrides a member in the base class 'Album'.
}Try

When enabled, TypeScript will check all code paths in a function to ensure they return a value.

ts
function lookupHeadphonesManufacturer(color: "blue" | "black"): string {
Function lacks ending return statement and return type does not include 'undefined'.2366Function lacks ending return statement and return type does not include 'undefined'.
  if (color === "blue") {
    return "beats";
  } else {
    ("bose");
  }
}Try

Raise error on ‘this’ expressions with an implied ‘any’ type.

For example, the class below returns a function which tries to access this.width and this.height – but the context for this inside the function inside getAreaFunction is not the instance of the Rectangle.

ts
class Rectangle {
  width: number;
  height: number;
 
  constructor(width: number, height: number) {
    this.width = width;
    this.height = height;
  }
 
  getAreaFunction() {
    return function () {
      return this.width * this.height;
'this' implicitly has type 'any' because it does not have a type annotation.
'this' implicitly has type 'any' because it does not have a type annotation.2683
2683'this' implicitly has type 'any' because it does not have a type annotation.
'this' implicitly has type 'any' because it does not have a type annotation.
    };
  }
}Try

This setting ensures consistency between accessing a field via the “dot” (obj.key) syntax, and “indexed” (obj["key"]) and the way which the property is declared in the type.

Without this flag, TypeScript will allow you to use the dot syntax to access fields which are not defined:

ts
interface GameSettings {
  // Known up-front properties
  speed: "fast" | "medium" | "slow";
  quality: "high" | "low";
 
  // Assume anything unknown to the interface
  // is a string.
  [key: string]: string;
}
 
const settings = getSettings();
settings.speed;
          
(property) GameSettings.speed: "fast" | "medium" | "slow"
settings.quality;
           
(property) GameSettings.quality: "high" | "low"
 
// Unknown key accessors are allowed on
// this object, and are `string`
settings.username;
            
(index) GameSettings[string]: stringTry

Turning the flag on will raise an error because the unknown field uses dot syntax instead of indexed syntax.

ts
const settings = getSettings();
settings.speed;
settings.quality;
 
// This would need to be settings["username"];
settings.username;
Property 'username' comes from an index signature, so it must be accessed with ['username'].4111Property 'username' comes from an index signature, so it must be accessed with ['username'].
            
(index) GameSettings[string]: stringTry

The goal of this flag is to signal intent in your calling syntax about how certain you are this property exists.

TypeScript has a way to describe objects which have unknown keys but known values on an object, via index signatures.

ts
interface EnvironmentVars {
  NAME: string;
  OS: string;
 
  // Unknown properties are covered by this index signature.
  [propName: string]: string;
}
 
declare const env: EnvironmentVars;
 
// Declared as existing
const sysName = env.NAME;
const os = env.OS;
      
const os: string
 
// Not declared, but because of the index
// signature, then it is considered a string
const nodeEnv = env.NODE_ENV;
        
const nodeEnv: stringTry

Turning on noUncheckedIndexedAccess will add undefined to any un-declared field in the type.

ts
declare const env: EnvironmentVars;
 
// Declared as existing
const sysName = env.NAME;
const os = env.OS;
      
const os: string
 
// Not declared, but because of the index
// signature, then it is considered a string
const nodeEnv = env.NODE_ENV;
        
const nodeEnv: string | undefinedTry

Report errors on unused local variables.

ts
const createKeyboard = (modelID: number) => {
  const defaultModelID = 23;
'defaultModelID' is declared but its value is never read.6133'defaultModelID' is declared but its value is never read.
  return { type: "keyboard", modelID };
};Try

Report errors on unused parameters in functions.

ts
const createDefaultKeyboard = (modelID: number) => {
'modelID' is declared but its value is never read.6133'modelID' is declared but its value is never read.
  const defaultModelID = 23;
  return { type: "keyboard", modelID: defaultModelID };
};Try

The strict flag enables a wide range of type checking behavior that results in stronger guarantees of program correctness. Turning this on is equivalent to enabling all of the strict mode family options, which are outlined below. You can then turn off individual strict mode family checks as needed.

Future versions of TypeScript may introduce additional stricter checking under this flag, so upgrades of TypeScript might result in new type errors in your program. When appropriate and possible, a corresponding flag will be added to disable that behavior.

When set, TypeScript will check that the built-in methods of functions call, bind, and apply are invoked with correct argument for the underlying function:

ts
// With strictBindCallApply on
function fn(x: string) {
  return parseInt(x);
}
 
const n1 = fn.call(undefined, "10");
 
const n2 = fn.call(undefined, false);
Argument of type 'boolean' is not assignable to parameter of type 'string'.2345Argument of type 'boolean' is not assignable to parameter of type 'string'.Try

Otherwise, these functions accept any arguments and will return any:

ts
// With strictBindCallApply off
function fn(x: string) {
  return parseInt(x);
}
 
// Note: No error; return type is 'any'
const n = fn.call(undefined, false);Try

When enabled, this flag causes functions parameters to be checked more correctly.

Here’s a basic example with strictFunctionTypes off:

ts
function fn(x: string) {
  console.log("Hello, " + x.toLowerCase());
}
 
type StringOrNumberFunc = (ns: string | number) => void;
 
// Unsafe assignment
let func: StringOrNumberFunc = fn;
// Unsafe call - will crash
func(10);Try

With strictFunctionTypes on, the error is correctly detected:

ts
function fn(x: string) {
  console.log("Hello, " + x.toLowerCase());
}
 
type StringOrNumberFunc = (ns: string | number) => void;
 
// Unsafe assignment is prevented
let func: StringOrNumberFunc = fn;
Type '(x: string) => void' is not assignable to type 'StringOrNumberFunc'.
  Types of parameters 'x' and 'ns' are incompatible.
    Type 'string | number' is not assignable to type 'string'.
      Type 'number' is not assignable to type 'string'.2322Type '(x: string) => void' is not assignable to type 'StringOrNumberFunc'.
  Types of parameters 'x' and 'ns' are incompatible.
    Type 'string | number' is not assignable to type 'string'.
      Type 'number' is not assignable to type 'string'.Try

During development of this feature, we discovered a large number of inherently unsafe class hierarchies, including some in the DOM. Because of this, the setting only applies to functions written in function syntax, not to those in method syntax:

ts
type Methodish = {
  func(x: string | number): void;
};
 
function fn(x: string) {
  console.log("Hello, " + x.toLowerCase());
}
 
// Ultimately an unsafe assignment, but not detected
const m: Methodish = {
  func: fn,
};
m.func(10);Try

When strictNullChecks is false, null and undefined are effectively ignored by the language. This can lead to unexpected errors at runtime.

When strictNullChecks is true, null and undefined have their own distinct types and you’ll get a type error if you try to use them where a concrete value is expected.

For example with this TypeScript code, users.find has no guarantee that it will actually find a user, but you can write code as though it will:

ts
declare const loggedInUsername: string;
 
const users = [
  { name: "Oby", age: 12 },
  { name: "Heera", age: 32 },
];
 
const loggedInUser = users.find((u) => u.name === loggedInUsername);
console.log(loggedInUser.age);Try

Setting strictNullChecks to true will raise an error that you have not made a guarantee that the loggedInUser exists before trying to use it.

ts
declare const loggedInUsername: string;
 
const users = [
  { name: "Oby", age: 12 },
  { name: "Heera", age: 32 },
];
 
const loggedInUser = users.find((u) => u.name === loggedInUsername);
console.log(loggedInUser.age);
'loggedInUser' is possibly 'undefined'.18048'loggedInUser' is possibly 'undefined'.Try

The second example failed because the array’s find function looks a bit like this simplification:

ts
// When strictNullChecks: true
type Array = {
  find(predicate: (value: any, index: number) => boolean): S | undefined;
};
// When strictNullChecks: false the undefined is removed from the type system,
// allowing you to write code which assumes it always found a result
type Array = {
  find(predicate: (value: any, index: number) => boolean): S;
};

When set to true, TypeScript will raise an error when a class property was declared but not set in the constructor.

ts
class UserAccount {
  name: string;
  accountType = "user";
 
  email: string;
Property 'email' has no initializer and is not definitely assigned in the constructor.2564Property 'email' has no initializer and is not definitely assigned in the constructor.
  address: string | undefined;
 
  constructor(name: string) {
    this.name = name;
    // Note that this.email is not set
  }
}Try

In the above case:

• this.name is set specifically.
• this.accountType is set by default.
• this.email is not set and raises an error.
• this.address is declared as potentially undefined which means it does not have to be set.

In TypeScript 4.0, support was added to allow changing the type of the variable in a catch clause from any to unknown. Allowing for code like:

ts
try {
  // ...
} catch (err: unknown) {
  // We have to verify err is an
  // error before using it as one.
  if (err instanceof Error) {
    console.log(err.message);
  }
}Try

This pattern ensures that error handling code becomes more comprehensive because you cannot guarantee that the object being thrown is a Error subclass ahead of time. With the flag useUnknownInCatchVariables enabled, then you do not need the additional syntax (: unknown) nor a linter rule to try enforce this behavior.

In TypeScript 5.0, when an import path ends in an extension that isn’t a known JavaScript or TypeScript file extension, the compiler will look for a declaration file for that path in the form of {file basename}.d.{extension}.ts. For example, if you are using a CSS loader in a bundler project, you might want to write (or generate) declaration files for those stylesheets:

css
/* app.css */
.cookie-banner {
  display: none;
}

ts
// app.d.css.ts
declare const css: {
  cookieBanner: string;
};
export default css;

ts
// App.tsx
import styles from "./app.css";
styles.cookieBanner; // string

By default, this import will raise an error to let you know that TypeScript doesn’t understand this file type and your runtime might not support importing it. But if you’ve configured your runtime or bundler to handle it, you can suppress the error with the new --allowArbitraryExtensions compiler option.

Note that historically, a similar effect has often been achievable by adding a declaration file named app.css.d.ts instead of app.d.css.ts - however, this just worked through Node’s require resolution rules for CommonJS. Strictly speaking, the former is interpreted as a declaration file for a JavaScript file named app.css.js. Because relative files imports need to include extensions in Node’s ESM support, TypeScript would error on our example in an ESM file under --moduleResolution node16 or nodenext.

For more information, read up the proposal for this feature and its corresponding pull request.

--allowImportingTsExtensions allows TypeScript files to import each other with a TypeScript-specific extension like .ts, .mts, or .tsx.

This flag is only allowed when --noEmit or --emitDeclarationOnly is enabled, since these import paths would not be resolvable at runtime in JavaScript output files. The expectation here is that your resolver (e.g. your bundler, a runtime, or some other tool) is going to make these imports between .ts files work.

当 allowUmdGlobalAccess 设置为 true 时，将允许你在模块文件中以全局变量的形式访问 UMD 的导出。 模块文件是具有或同时导入、导出的文件。当未设置这个选项时，使用 UMD 模块的导出需要首先导入声明。

一个典型场景是：在一个 Web 项目中， 您知道特定的库（如 jQuery 或 Lodash ）在运行时总是可用的，但您无法通过导入来使用他们。

可以让您设置解析非绝对路径模块名时的基准目录。

你可以定义一个根目录，以进行绝对路径文件解析。例如：

baseUrl
├── ex.ts
├── hello
│   └── world.ts
└── tsconfig.json

在这个项目中被配置为 "baseUrl": "./"，TypeScript 将会从首先寻找与 tsconfig.json 处于相同目录的文件。

ts
import { helloWorld } from "hello/world";
console.log(helloWorld);

当你厌倦了导入文件时总是 "../" 或 "./"，或需要在移动文件时更改路径，这是一个很好的解决方法。

--customConditions takes a list of additional conditions that should succeed when TypeScript resolves from an exports or imports field of a package.json. These conditions are added to whatever existing conditions a resolver will use by default.

For example, when this field is set in a tsconfig.json as so:

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

Any time an exports or imports field is referenced in package.json, TypeScript will consider conditions called my-condition.

So when importing from a package with the following package.json

jsonc
{
  // ...
  "exports": {
    ".": {
      "my-condition": "./foo.mjs",
      "node": "./bar.mjs",
      "import": "./baz.mjs",
      "require": "./biz.mjs"
    }
  }
}

TypeScript will try to look for files corresponding to foo.mjs.

This field is only valid under the node16, nodenext, and bundler options for --moduleResolution.

设置程序的模块系统。在 模块 参考页面获取更多信息。你很可能要用 "CommonJS"。

改变 module 可能会影响 moduleResolution，它也有 一个参考页。

下面是这个文件的一些输出例子：

ts
// @filename: index.ts
import { valueOfPi } from "./constants";
 
export const twoPi = valueOfPi * 2;Try

CommonJS

ts
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.twoPi = void 0;
const constants_1 = require("./constants");
exports.twoPi = constants_1.valueOfPi * 2;
 Try

UMD

ts
(function (factory) {
    if (typeof module === "object" && typeof module.exports === "object") {
        var v = factory(require, exports);
        if (v !== undefined) module.exports = v;
    }
    else if (typeof define === "function" && define.amd) {
        define(["require", "exports", "./constants"], factory);
    }
})(function (require, exports) {
    "use strict";
    Object.defineProperty(exports, "__esModule", { value: true });
    exports.twoPi = void 0;
    const constants_1 = require("./constants");
    exports.twoPi = constants_1.valueOfPi * 2;
});
 Try

AMD

ts
define(["require", "exports", "./constants"], function (require, exports, constants_1) {
    "use strict";
    Object.defineProperty(exports, "__esModule", { value: true });
    exports.twoPi = void 0;
    exports.twoPi = constants_1.valueOfPi * 2;
});
 Try

System

ts
System.register(["./constants"], function (exports_1, context_1) {
    "use strict";
    var constants_1, twoPi;
    var __moduleName = context_1 && context_1.id;
    return {
        setters: [
            function (constants_1_1) {
                constants_1 = constants_1_1;
            }
        ],
        execute: function () {
            exports_1("twoPi", twoPi = constants_1.valueOfPi * 2);
        }
    };
});
 Try

ESNext

ts
import { valueOfPi } from "./constants";
export const twoPi = valueOfPi * 2;
 Try

ES2020

ts
import { valueOfPi } from "./constants";
export const twoPi = valueOfPi * 2;
 Try

None

ts
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.twoPi = void 0;
const constants_1 = require("./constants");
exports.twoPi = constants_1.valueOfPi * 2;
 Try

指定模块解析策略：'node' （Node.js） 或 'classic' （在 TypeScript 1.6 版本之前使用）。 你可能不需要在新代码中使用 classic。

这里有一个关于模块解析的手册参考。

Provides a way to override the default list of file name suffixes to search when resolving a module.

{
  "compilerOptions": {
    "moduleSuffixes": [".ios", ".native", ""]
  }
}

Given the above configuration, an import like the following:

ts
import * as foo from "./foo";

TypeScript will look for the relative files ./foo.ios.ts, ./foo.native.ts, and finally ./foo.ts.

Note the empty string "" in moduleSuffixes which is necessary for TypeScript to also look-up ./foo.ts.

This feature can be useful for React Native projects where each target platform can use a separate tsconfig.json with differing moduleSuffixes.

By default, TypeScript will examine the initial set of files for import and <reference directives and add these resolved files to your program.

If noResolve is set, this process doesn’t happen. However, import statements are still checked to see if they resolve to a valid module, so you’ll need to make sure this is satisfied by some other means.

In JavaScript it’s possible to import a module without actually importing any values from it.

ts
import "some-module";

These imports are often called side effect imports because the only useful behavior they can provide is by executing some side effect (like registering a global variable, or adding a polyfill to a prototype).

By default, TypeScript will not check these imports for validity. If the import resolves to a valid source file, TypeScript will load and check the file. If no source file is found, TypeScript will silently ignore the import.

This is surprising behavior, but it partially stems from modeling patterns in the JavaScript ecosystem. For example, this syntax has also been used with special loaders in bundlers to load CSS or other assets. Your bundler might be configured in such a way where you can include specific .css files by writing something like the following:

tsx
import "./button-component.css";
export function Button() {
  // ...
}

Still, this masks potential typos on side effect imports.

When --noUncheckedSideEffectImports is enabled, TypeScript will error if it can’t find a source file for a side effect import.

ts
import "oops-this-module-does-not-exist";
//     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// error: Cannot find module 'oops-this-module-does-not-exist' or its corresponding
//        type declarations.

When enabling this option, some working code may now receive an error, like in the CSS example above. To work around this, users who want to just write side effect imports for assets might be better served by writing what’s called an ambient module declaration with a wildcard specifier. It would go in a global file and look something like the following:

ts
// ./src/globals.d.ts
// Recognize all CSS files as module imports.
declare module "*.css" {}

In fact, you might already have a file like this in your project! For example, running something like vite init might create a similar vite-env.d.ts.

一些将模块导入重新映射到相对于 baseUrl 路径的配置。手册中有更多关于 paths 的内容。

paths 可以允许你声明 TypeScript 应该如何解析你的 require/import。

{
  "compilerOptions": {
    "baseUrl": ".", // this must be specified if "paths" is specified.
    "paths": {
      "jquery": ["node_modules/jquery/dist/jquery"] // this mapping is relative to "baseUrl"
    }
  }
}

这将使你可以写 import "jquery"，并且在本地获得所有正确的类型。

{
  "compilerOptions": {
    "baseUrl": "src",
    "paths": {
        "app/*": ["app/*"],
        "config/*": ["app/_config/*"],
        "environment/*": ["environments/*"],
        "shared/*": ["app/_shared/*"],
        "helpers/*": ["helpers/*"],
        "tests/*": ["tests/*"]
    },
}

这种情况下，你可以告诉 TypeScript 文件解析器支持一些自定义的前缀来寻找代码。 这种模式可以避免在你的代码中出现过长的相对路径。

Allows importing modules with a .json extension, which is a common practice in node projects. This includes generating a type for the import based on the static JSON shape.

TypeScript does not support resolving JSON files by default:

ts
// @filename: settings.json
{
    "repo": "TypeScript",
    "dry": false,
    "debug": false
}
// @filename: index.ts
import settings from "./settings.json";
Cannot find module './settings.json'. Consider using '--resolveJsonModule' to import module with '.json' extension.2732Cannot find module './settings.json'. Consider using '--resolveJsonModule' to import module with '.json' extension.
 
settings.debug === true;
settings.dry === 2;Try

Enabling the option allows importing JSON, and validating the types in that JSON file.

ts
// @filename: settings.json
{
    "repo": "TypeScript",
    "dry": false,
    "debug": false
}
// @filename: index.ts
import settings from "./settings.json";
 
settings.debug === true;
settings.dry === 2;
This comparison appears to be unintentional because the types 'boolean' and 'number' have no overlap.2367This comparison appears to be unintentional because the types 'boolean' and 'number' have no overlap.Try

--resolvePackageJsonExports forces TypeScript to consult the exports field of package.json files if it ever reads from a package in node_modules.

This option defaults to true under the node16, nodenext, and bundler options for --moduleResolution.

--resolvePackageJsonImports forces TypeScript to consult the imports field of package.json files when performing a lookup that starts with # from a file whose ancestor directory contains a package.json.

This option defaults to true under the node16, nodenext, and bundler options for --moduleResolution.

默认: 所有输入的非声明文件中的最长公共路径。若 composite 被指定，则是包含 tsconfig.json 文件的目录。

当 TypeScript 编译文件时，它在输出目录中保持与输入目录中相同的目录结构。

例如，假设你有一些输入文件：

MyProj
├── tsconfig.json
├── core
│   ├── a.ts
│   ├── b.ts
│   ├── sub
│   │   ├── c.ts
├── types.d.ts

rootDir 推断的结构是所有非声明输入文件的最长公共路径，在例子中为 core/。

如果你的 outDir 是 dist，TypeScript 将会生成这样的文件树：

MyProj
├── dist
│   ├── a.ts
│   ├── b.ts
│   ├── sub
│   │   ├── c.ts

但你可能希望让 core 成为输出目录结构的一部分。 通过在 tsconfig.json 中指定 rootDir: "."，TypeScript 将会生成这样的文件树：

MyProj
├── dist
│   ├── core
│   │   ├── a.js
│   │   ├── b.js
│   │   ├── sub
│   │   │   ├── c.js

重要的是，rootDir 不会影响哪些文件被包含在编译中。 它与 tsconfig.json 中 include，exclude，or files 的选项没有关系。

请注意，TypeScript 永远不会将输出文件写入 outDir 之外的目录，也不会忽略生成某些文件。 处于这个原因，rootDir 页强制要求所有需要被生成的文件都在 rootDir 路径下。

例如，假设你有这样的文件树：

MyProj
├── tsconfig.json
├── core
│   ├── a.ts
│   ├── b.ts
├── helpers.ts

将 rootDir 指定为 core，并且 将 include 指定为 * 是错误的，因为它会创建一个文件（helpers.ts），这个文件会被生成在 outDir 之外 （即 ../helpers.js）。

通过 rootDirs，你可以告诉编译器有许多“虚拟”的目录作为一个根目录。这将会允许编译器在这些“虚拟”目录中解析相对应的模块导入，就像它们被合并到同一目录中一样。

例如：

 src
 └── views
     └── view1.ts (can import "./template1", "./view2`)
     └── view2.ts (can import "./template1", "./view1`)
 generated
 └── templates
         └── views
             └── template1.ts (can import "./view1", "./view2")

{
  "compilerOptions": {
    "rootDirs": ["src/views", "generated/templates/views"]
  }
}

这不会影响到 TypeScript 如何生成 JavaScript，而仅是模拟了假设它们在运行时能通过这些相对路径工作。

默认情况下，所有 可见 的 ”@types” 包都将包含在你的编译过程中。 在 node_modules/@types 中的任何包都被认为是 可见 的。 例如，这意味着包含 ./node_modules/@types/，../node_modules/@types/，../../node_modules/@types/ 中所有的包。

当 typeRoots 被指定，仅有 在 typeRoots 下的包会被包含。例如：

{
  "compilerOptions": {
    "typeRoots": ["./typings", "./vendor/types"]
  }
}

这个配置文件将包含 ./typings 和 ./vendor/types 下的所有包，而不包括 ./node_modules/@types 下的。其中所有的路径都是相对于 tsconfig.json。

默认情况下，所有 可见 的 ”@types” 包都将包含在你的编译过程中。 在 node_modules/@types 中的任何包都被认为是 可见 的。 例如，这意味着包含 ./node_modules/@types/，../node_modules/@types/，../../node_modules/@types/ 中所有的包。。

当 types 被指定，则只有列出的包才会被包含在全局范围内。例如：

{
  "compilerOptions": {
    "types": ["node", "jest", "express"]
  }
}

这个 tsconfig.json 文件将 只会 包含 ./node_modules/@types/node，./node_modules/@types/jest 和 ./node_modules/@types/express。 其他在 node_modules/@types/* 下的包将不会被包含。

这会影响什么？

此选项不会影响 @types/* 如何被包含在你的代码中，例如你在有上面例子里 compilerOptions 的环境中写了这样的代码：

ts
import * as moment from "moment";
moment().format("MMMM Do YYYY, h:mm:ss a");

moment 导入会有完整的类型。

当你设置了这个选项，通过不在 types 数组中包含，它将：

• 不会再你的项目中添加全局声明（例如 node 中的 process 或 Jest 中的 expect）
• 导出不会出现再自动导入的建议中

此功能与 类型根路径 不同的是，它只指定你想要包含的具体类型，而 类型根路径 支持你想要特定的文件夹。

为你工程中的每个 TypeScript 或 JavaScript 文件生成 .d.ts 文件。 这些 .d.ts 文件是描述模块外部 API 的类型定义文件。 像 TypeScript 这样的哦你根据可以通过 .d.ts 文件为非类型化的代码提供 intellisense 和精确的类型。

当 declaration 设置为 true 时，用编译器执行下面的 TypeScript 代码：

ts
export let helloWorld = "hi";Try

将会生成如下这样的 index.js 文件：

ts
export let helloWorld = "hi";
 Try

以及一个相应的 helloWorld.d.ts：

ts
export declare let helloWorld: string;
 Try

当使用 .d.ts 文件处理 JavaScript 文件时，你可能需要使用 emitDeclarationOnly 或 outDir 来确保 JavaScript 文件不会被覆盖。

Offers a way to configure the root directory for where declaration files are emitted.

example
├── index.ts
├── package.json
└── tsconfig.json

with this tsconfig.json:

{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "./types"
  }
}

Would place the d.ts for the index.ts in a types folder:

example
├── index.js
├── index.ts
├── package.json
├── tsconfig.json
└── types
    └── index.d.ts

Generates a source map for .d.ts files which map back to the original .ts source file. This will allow editors such as VS Code to go to the original .ts file when using features like Go to Definition.

You should strongly consider turning this on if you’re using project references.

‘降级’ 是 TypeScript 的术语，指用于转换到旧版本的 JavaScript。 这个选项是为了在旧版 Javascript 运行时上更准确的实现现代 JavaScript 迭代器的概念。

ECMAScript 6 增加了几个新的迭代器原语：for / of 循环（for (el of arr)），数组展开（[a, ...b]），参数展开（fn(...args)）和 Symbol.iterator。

如果 Symbol.iterator 存在的话，--downlevelIteration 将允许在 ES5 环境更准确的使用这些迭代原语。

例：for / of 的效果

对于 TypeScript 代码：

ts
const str = "Hello!";
for (const s of str) {
  console.log(s);
}Try

如果没有启用 downlevelIteration，for / of 循环将被降级为传统的 for 循环：

ts
"use strict";
var str = "Hello!";
for (var _i = 0, str_1 = str; _i < str_1.length; _i++) {
    var s = str_1[_i];
    console.log(s);
}
 Try

这通常是人们所期望的，但是它并不是 100% 符合 ECMAScript 迭代器协议。 某些字符串，例如 emoji （😜），其 .length 为 2（甚至更多），但在 for-of 循环中应只有一次迭代。 可以在 Jonathan New 的这篇文章中 找到更详细的解释。

当 downlevelIteration 启用时，TypeScript 将会使用辅助函数来检查 Symbol.iterator 的实现（无论是原生实现还是 polyfill）。 如果没有实现，则将会回退到基于索引的迭代。

ts
"use strict";
var __values = (this && this.__values) || function(o) {
    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
    if (m) return m.call(o);
    if (o && typeof o.length === "number") return {
        next: function () {
            if (o && i >= o.length) o = void 0;
            return { value: o && o[i++], done: !o };
        }
    };
    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
};
var e_1, _a;
var str = "Hello!";
try {
    for (var str_1 = __values(str), str_1_1 = str_1.next(); !str_1_1.done; str_1_1 = str_1.next()) {
        var s = str_1_1.value;
        console.log(s);
    }
}
catch (e_1_1) { e_1 = { error: e_1_1 }; }
finally {
    try {
        if (str_1_1 && !str_1_1.done && (_a = str_1.return)) _a.call(str_1);
    }
    finally { if (e_1) throw e_1.error; }
}
 Try

你也可以通过 importHelpers 来使用 tslib 以减少被内联的 JavaScript 的数量：

ts
"use strict";
var __values = (this && this.__values) || function(o) {
    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
    if (m) return m.call(o);
    if (o && typeof o.length === "number") return {
        next: function () {
            if (o && i >= o.length) o = void 0;
            return { value: o && o[i++], done: !o };
        }
    };
    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
};
var e_1, _a;
var str = "Hello!";
try {
    for (var str_1 = __values(str), str_1_1 = str_1.next(); !str_1_1.done; str_1_1 = str_1.next()) {
        var s = str_1_1.value;
        console.log(s);
    }
}
catch (e_1_1) { e_1 = { error: e_1_1 }; }
finally {
    try {
        if (str_1_1 && !str_1_1.done && (_a = str_1.return)) _a.call(str_1);
    }
    finally { if (e_1) throw e_1.error; }
}
 Try

注： 如果在运行时不存在 Symbol.iterator，启用 downlevelIteration 将不会提高合规性。

例：数组展开的效果

这是一个数组展开：

js
// 构建一个新的数组，其元素首先为 1，然后是 arr2 的元素。
const arr = [1, ...arr2];

根据描述，听起来很容易降级到 ES5：

js
// The same, right?
const arr = [1].concat(arr2);

但是在某些罕见的情况下会明显不同。例如如果数组中有一个“洞”，缺失的索引在展开时将创建一个 自己的 属性，但若使用 concat 则不会：

js
// 构建一个元素 `1` 不存在的数组
let missing = [0, , 1];
let spreaded = [...missing];
let concated = [].concat(missing);
// true
"1" in spreaded;
// false
"1" in concated;

就像 for / of 一样，downlevelIteration 将使用 Symbol.iterator（如果存在的话）来更准确的模拟 ES6 的行为。

Controls whether TypeScript will emit a byte order mark (BOM) when writing output files. Some runtime environments require a BOM to correctly interpret a JavaScript files; others require that it is not present. The default value of false is generally best unless you have a reason to change it.

Only emit .d.ts files; do not emit .js files.

This setting is useful in two cases:

• You are using a transpiler other than TypeScript to generate your JavaScript.
• You are using TypeScript to only generate d.ts files for your consumers.

对于某些降级行为，TypeScript 使用一些辅助代码来进行操作。例如继承类，展开数组或对象，以及异步操作。 默认情况下，这些辅助代码被插入到使用它们的文件中。 如果在许多不同的模块中使用相同的辅助代码，则可能会导致代码重复。

如果启用了 importHelpers 选项，这些辅助函数将从 tslib 中被导入。 你需要确保 tslib 模块在运行时可以被导入。 这只影响模块，全局脚本文件不会尝试导入模块。

例如，对于如下 TypeScript 代码：

ts
export function fn(arr: number[]) {
  const arr2 = [1, ...arr];
}

开启 downlevelIteration 并且 importHelpers 仍为 false：

ts
var __read = (this && this.__read) || function (o, n) {
    var m = typeof Symbol === "function" && o[Symbol.iterator];
    if (!m) return o;
    var i = m.call(o), r, ar = [], e;
    try {
        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
    }
    catch (error) { e = { error: error }; }
    finally {
        try {
            if (r && !r.done && (m = i["return"])) m.call(i);
        }
        finally { if (e) throw e.error; }
    }
    return ar;
};
var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
        if (ar || !(i in from)) {
            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
            ar[i] = from[i];
        }
    }
    return to.concat(ar || Array.prototype.slice.call(from));
};
export function fn(arr) {
    var arr2 = __spreadArray([1], __read(arr), false);
}
 Try

同时开始 downlevelIteration 和 importHelpers：

ts
import { __read, __spreadArray } from "tslib";
export function fn(arr) {
    var arr2 = __spreadArray([1], __read(arr), false);
}
 Try

当你提供了自行实现的这些函数时，你可以使用 noEmitHelpers。

When set, instead of writing out a .js.map file to provide source maps, TypeScript will embed the source map content in the .js files. Although this results in larger JS files, it can be convenient in some scenarios. For example, you might want to debug JS files on a webserver that doesn’t allow .map files to be served.

Mutually exclusive with sourceMap.

For example, with this TypeScript:

ts
const helloWorld = "hi";
console.log(helloWorld);

Converts to this JavaScript:

ts
"use strict";
const helloWorld = "hi";
console.log(helloWorld);
 Try

Then enable building it with inlineSourceMap enabled there is a comment at the bottom of the file which includes a source-map for the file.

ts
"use strict";
const helloWorld = "hi";
console.log(helloWorld);
//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyJpbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUEsTUFBTSxVQUFVLEdBQUcsSUFBSSxDQUFDO0FBQ3hCLE9BQU8sQ0FBQyxHQUFHLENBQUMsVUFBVSxDQUFDLENBQUMifQ==Try

When set, TypeScript will include the original content of the .ts file as an embedded string in the source map (using the source map’s sourcesContent property). This is often useful in the same cases as inlineSourceMap.

Requires either sourceMap or inlineSourceMap to be set.

For example, with this TypeScript:

ts
const helloWorld = "hi";
console.log(helloWorld);Try

By default converts to this JavaScript:

ts
"use strict";
const helloWorld = "hi";
console.log(helloWorld);
 Try

Then enable building it with inlineSources and inlineSourceMap enabled there is a comment at the bottom of the file which includes a source-map for the file. Note that the end is different from the example in inlineSourceMap because the source-map now contains the original source code also.

ts
"use strict";
const helloWorld = "hi";
console.log(helloWorld);
//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyJpbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUEsTUFBTSxVQUFVLEdBQUcsSUFBSSxDQUFDO0FBQ3hCLE9BQU8sQ0FBQyxHQUFHLENBQUMsVUFBVSxDQUFDLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJjb25zdCBoZWxsb1dvcmxkID0gXCJoaVwiO1xuY29uc29sZS5sb2coaGVsbG9Xb3JsZCk7Il19Try

Specify the location where debugger should locate map files instead of generated locations. This string is treated verbatim inside the source-map, for example:

{
  "compilerOptions": {
    "sourceMap": true,
    "mapRoot": "https://my-website.com/debug/sourcemaps/"
  }
}

Would declare that index.js will have sourcemaps at https://my-website.com/debug/sourcemaps/index.js.map.

Specify the end of line sequence to be used when emitting files: ‘CRLF’ (dos) or ‘LF’ (unix).

禁止编译器生成文件，例如 JavaScript 代码，source-map 或声明。

这为另一个工具提供了空间，例如用 Babel 或 swc 来处理将 TypeScript 转换为可以在 JavaScript 环境中运行的文件的过程。

然后你可以使用 TypeScript 作为提供编辑器集成的工具，或用来对源码进行类型检查。

Instead of importing helpers with importHelpers, you can provide implementations in the global scope for the helpers you use and completely turn off emitting of helper functions.

For example, using this async function in ES5 requires a await-like function and generator-like function to run:

ts
const getAPI = async (url: string) => {
  // Get API
  return {};
};Try

Which creates quite a lot of JavaScript:

ts
"use strict";
var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
    return new (P || (P = Promise))(function (resolve, reject) {
        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
        step((generator = generator.apply(thisArg, _arguments || [])).next());
    });
};
var __generator = (this && this.__generator) || function (thisArg, body) {
    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
    function verb(n) { return function (v) { return step([n, v]); }; }
    function step(op) {
        if (f) throw new TypeError("Generator is already executing.");
        while (g && (g = 0, op[0] && (_ = 0)), _) try {
            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
            if (y = 0, t) op = [op[0] & 2, t.value];
            switch (op[0]) {
                case 0: case 1: t = op; break;
                case 4: _.label++; return { value: op[1], done: false };
                case 5: _.label++; y = op[1]; op = [0]; continue;
                case 7: op = _.ops.pop(); _.trys.pop(); continue;
                default:
                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
                    if (t[2]) _.ops.pop();
                    _.trys.pop(); continue;
            }
            op = body.call(thisArg, _);
        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
    }
};
var getAPI = function (url) { return __awaiter(void 0, void 0, void 0, function () {
    return __generator(this, function (_a) {
        // Get API
        return [2 /*return*/, {}];
    });
}); };
 Try

Which can be switched out with your own globals via this flag:

ts
"use strict";
var getAPI = function (url) { return __awaiter(void 0, void 0, void 0, function () {
    return __generator(this, function (_a) {
        // Get API
        return [2 /*return*/, {}];
    });
}); };
 Try

Do not emit compiler output files like JavaScript source code, source-maps or declarations if any errors were reported.

This defaults to false, making it easier to work with TypeScript in a watch-like environment where you may want to see results of changes to your code in another environment before making sure all errors are resolved.

如果被指定，.js （以及 .d.ts, .js.map 等）将会被生成到这个目录下。 原始源文件的目录将会被保留，如果计算出的根目录不是你想要的，可以查看 rootDir。

如果没有指定，.js 将被生成至于生成它们的 .ts 文件相同的目录中：

sh
$ tsc
example
├── index.js
└── index.ts

使用类似这样的 tsconfig.json：

{
  "compilerOptions": {
    "outDir": "dist"
  }
}

使用这些配置运行 tsc 时，会将文件移动到指定的 dist 文件夹中：

sh
$ tsc
example
├── dist
│   └── index.js
├── index.ts
└── tsconfig.json

如果被指定，所有 全局 （非模块） 文件将被合并到指定的单个输出文件中。

如果 module 为 system 或 amd，所有模块文件也将在所有全局内容之后被合并到这个文件中。

注：除非 module 是 None，System 或 AMD， 否则不能使用 outFile。 这个选项 不能 用来打包 CommonJS 或 ES6 模块。