TSConfig Reference

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

Default: [] if files is specified, otherwise ["**/*"]

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

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.

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)
• **/ recursively matches any subdirectory

If a glob pattern doesn’t include a file extension, then only files with supported extensions are included (e.g. .ts, .tsx, and .d.ts by default, with .js and .jsx if allowJs is set to true).

Default: ["node_modules", "bower_components", "jspm_packages"], plus the value of outDir if one is specified.

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 program 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 program - it simply changes what the include setting finds.

TODO

TODO

TODO

Enable incremental compilation

Allowed Values: ES3 (default), ES5, ES6/ES2015 (synonomous), ES7/ES2016, ES2017, ES2018, ES2019, ESNext

All modern browsers support all ES6 features, so ES6 is a good choice. You might choose to set a lower target if your code is deployed to older environments, or a higher target if your code only runs on newer environments.

The target setting changes which JS features are downleveled or left intact. For example, an arrow function () => this will be turned into an equivalent function expression if target is ES5 or lower.

target also changes the default value of [[lib]]. You may “mix and match” target and lib settings as desired.

The value ESNext refers to whatever the highest version TypeScript supports at the time is. This setting should be used with caution, since it doesn’t mean the same thing between TypeScript versions and can make upgrades less predictable.

Allowed Values: CommonJS (default if target is ES3 or ES5), ES6/ES2015 (synonymous, default for target ES6 and higher), None, UMD, AMD, System, ESNext

Sets the module system for the program. See the [[Modules]] chapter for more information.

Default: At a minimum ["dom"], plus more depending on target

TypeScript includes a default set of type definitions for built-in JS APIs (like Math), as well as type definitions for things found in browser environments (like document). TypeScript also includes APIs for newer JS features matching the target you specify; for example the definition for Map is available if target is ES6 or newer.

You may want to change these for a few reasons:

• Your program doesn’t run in a browser, so you don’t want the "dom" type definitions
• Your runtime platform provides certain JavaScript API objects (maybe through polyfills), but doesn’t yet support the full syntax of a given ECMAScript version
• You have polyfills or native implementations for some, but not all, of a higher level ECMAScript version

Allow javascript files to be compiled.

Report errors in .js files.

Allowed Values: react (default), react-native, preserve

Controls how JSX constructs are emitted in JavaScript files. This only affects output of JS files that started in .tsx files.

• preserve: Emit .jsx files with the JSX unchanged
• react: Emit .js files with JSX changed to the equivalent React.createElement calls
• react-native: Emit .js files with the JSX unchanged

Generates corresponding ‘.d.ts’ file.

Generates a source map for .d.ts files that maps 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.

Enables the generation of sourcemap files. These files allow debuggers and other tools to display the original TypeScript source code when actually working with the emitted JavaScript files. Source map files are emitted as .js.map (or .jsx.map) files next to the corresponding .js output file.

The .js files will in turn contain a sourcemap comment to indicate to tools where the files are:

js
//# sourceMappingURL=main.js.map

If specified, all global (non-module) files will be concatenated into the single output file specified.

If module is system or amd, all module files will also be concatenated into this file after all global content.

Note: outFile cannot be used unless module is None, System, or AMD. This option cannot be used to bundle CommonJS or ES6 modules.

If specified, .js (as well as .d.ts, .js.map, etc.) files will be emitted in the specified directory. The directory structure of the original source files is preserved; see [[rootDir]] if the computed root is not what you intended.

If not specified, .js files will be emitted in the same directory as the .ts files they were generated from.

Default: The longest common path of all non-declaration input files. If composite is set, the default is instead the directory containing the tsconfig.json file.

When TypeScript compiles files, it keeps the same directory structure in the output directory as exists in the input directory.

For example, let’s say you have some input files:

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

The inferred value for rootDir is the longest common path of all non-declaration input files, which in this case is core/.

If your outDir was dist, TypeScript would write this tree:

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

However, you may have intended for core to be part of the output directory structure. By setting rootDir: "." in tsconfig.json, TypeScript would write this tree:

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

Importantly, rootDir does not affect which files become part of the compilation. It has no interaction with the include, exclude, or files tsconfig.json settings.

Note that TypeScript will never write an output file to a directory outside of outDir, and will never skip emitting a file. For this reason, rootDir also enforces that all files which need to be emitted are underneath the rootDir path.

For example, let’s say you had this tree:

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

It would be an error to specify rootDir as core and include as * because it creates a file (helpers.ts) that would need to be emitted outside the outDir (i.e. ../helpers.js).

The composite option enforces certain constraints that make it possible for build tools (including TypeScript itself, under --build mode) to quickly determine if a project has been built yet.

When this setting is on:

• The rootDir setting, if not explicitly set, defaults to the directory containing the tsconfig.json file.
• All implementation files must be matched by an include pattern or listed in the files array. If this constraint is violated, tsc will inform you which files weren’t specified.
• declaration defaults to true

Specify file to store incremental compilation information

Do not emit comments to output.

Do not emit outputs.

For certain downleveling operations, TypeScript uses some helper code for operations like extending class, spreading arrays/objects, and async operations. By default, these helpers are inserted into files which use them. This can result in code duplication if the same helper is used in many different modules.

If the importHelpers flag is on, these helper functions are instead imported from the tslib module. You will need to ensure that the tslib module is able to be imported at runtime. This only affects modules; global script files will not attempt to import modules.

ts
// @showEmit
// @target: ES5
// @downleveliteration
// --importHelpers off: Spread helper is inserted into the file
// Note: This example also uses --downlevelIteration
export function fn(arr: number[]) {
  const arr2 = [1, ...arr];
}

ts
// @showEmit
// @target: ES5
// @downleveliteration
// @importhelpers
// --importHelpers on: Spread helper is inserted imported from 'tslib'
export function fn(arr: number[]) {
  const arr2 = [1, ...arr];
}

noEmitHelpers

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:

ts
// @showEmit
// @target: ES5
// @downleveliteration
// @noemithelpers

// __spread is assumed to be available
export function fn(arr: number[]) {
  const arr2 = [1, ...arr];
}

Default: false. Has no effect if target is ES6 or newer.

ECMAScript 6 added several new iteration primitives: the for / of loop (for (el of arr)), Array spread ([a, ...b]), argument spread (fn(...args)), and Symbol.iterator. --downlevelIteration allows for these iteration primitives to be used more accurately in ES5 environments if a Symbol.iterator implementation is present.

Example: Effects on for / of

Without downlevelIteration on, a for / of loop on any object is downleveled to a traditional for loop:

js
"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);
}

This is often what people expect, but it’s not 100% compliant with ECMAScript 6 behavior. Certain strings, such as emoji (😜), have a .length of 2 (or even more!), but should iterate as 1 unit in a for-of loop. See this blog post by Jonathan New for a longer explanation.

When downlevelIteration is enabled, TypeScript will use a helper function that checks for a Symbol.iterator implementation (either native or polyfill). If this implementation is missing, you’ll fall back to index-based iteration.

js
"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; }
}

Note: Remember, downlevelIteration does not improve compliance if Symbol.iterator is not present!

Example: Effects on Array Spreads

This is an array spread:

js
// Make a new array who elements are 1 followed by the elements of arr2
const arr = [1, ...arr2];

Based on the description, it sounds easy to downlevel to ES5:

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

However, this is observably different in certain rare cases. For example, if an array has a “hole” in it, the missing index will create an own property if spreaded, but will not if built using concat:

js
// Make an array where the '1' element is missing
let missing = [0, , 1];
let spreaded = [...missing];
let concated = [].concat(missing);

// true
"1" in spreaded;
// false
"1" in concated;

Just as with for / of, downlevelIteration will use Symbol.iterator (if present) to more accurately emulate ES 6 behavior.

While you can use TypeScript to produce JavaScript code from TypeScript code, it’s also common to use other transpilers such as Babel to do this. However, most other transpilers only operate on a single file at a time, so can’t apply code transforms that depend on whole-program analysis. This restriction also applies to TypeScript’s ts.transpileModule API which is used by some build tools.

These limitations can cause runtime problems for some TypeScript constructs. Setting the isolatedModules flag tells TypeScript to warn you if you write certain code that can’t be correctly interpreted by a single-file transpilation process. It does not change the behavior of your code, or otherwise change the behavior of TypeScript’s checking and emitting process.

Exports of Non-Value Identifiers

In TypeScript, you can import a type and then subsequently export it:

ts
// @noErrors
import { someType, someFunction } from "someModule";

someFunction();

export { someType, someFunction };

Because there’s no value for someType, the emitted export will not try to export it (this would be a runtime error):

js
export { someFunction };

Single-file transpilers don’t know whether someType produces a value or not, so it’s an error to export a name that only refers to a type if isolatedModules is set.

Non-Module Files

If isolatedModules is set, all implementation files must be modules. An error occurs if any file isn’t a module:

ts
// @isolatedModules
function fn() {}

This restriction doesn’t apply to .d.ts files

References to const enum members

In TypeScript, when you reference a const enum member, the reference is replaced by its actual value in the emitted JavaScript:

ts
// @showEmit
// @removeComments
declare const enum Numbers {
  Zero = 0,
  One = 1
}
console.log(Numbers.Zero + Numbers.One);

Without knowledge of the values of these members, other transpilers can’t replace the references to Number, which would be a runtime error if left alone (since there is no Numbers object at runtime). Because of this, when isolatedModules is set, it is an error to reference an ambient const enum member.

✅ We recommend enabling this in all codebases, especially new ones

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.

✅ We strongly recommend enabling this in all codebases

Default: false, unless strict is set

In some cases where no type annotations are present, TypeScript will fall back to a type of any for a variable. This can cause some errors to be missed:

ts
// @noImplicitAny: false
function fn(s) {
  // No error?
  console.log(s.subtr(3));
}
fn(42);

When noImplicitAny is set, TypeScript will issue an error whenever it would have inferred any:

ts
function fn(s) {
  console.log(s.subtr(3));
}

Default: false, unless strict is set

When strictNullChecks is false, null and undefined are considered to be valid values of all types. 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.

✅ We strongly recommend enabling this in all codebases

Default: false, unless strict is set

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

Here’s a basic example with strictFunctionTypes off:

ts
// @strictFunctionTypes: false
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);

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;

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);

Default: false, unless strict is set.

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);

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

ts
// @strictBindCallApply: false

// With strictBindCallApply off
function fn(x: string) {
   return parseInt(x);
}

// Note: No error; return type is 'any'
const n = fn.call(undefined, false);
      ^?

When set, it becomes an error to declare a class property without directly initializing it before the end of the constructor.

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

Parse in strict mode and emit “use strict” for each source file.

Specify module resolution strategy: ‘node’ (Node.js) or ‘classic’ (TypeScript pre-1.6).

Base directory to resolve non-absolute module names.

A series of entries which re-map imports to lookup locations relative to the ‘baseUrl’.

List of root folders whose combined content represents the structure of the project at runtime.

List of folders to include type definitions from.

Type declaration files to be included in compilation.

Allow default imports from modules with no default export. This does not affect code emit, just typechecking.

Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies ‘allowSyntheticDefaultImports’.

Do not resolve the real path of symlinks.

Allow accessing UMD globals from modules.

Specify the location where debugger should locate TypeScript files instead of source locations.

Specify the location where debugger should locate map files instead of generated locations.

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.

When set, TypeScript will include the original content of the .ts file as an embedded string in the source map. This is often useful in the same cases as inlineSourceMap.

Requires either sourceMap or inlineSourceMap to be set.

Report errors on unused locals.

Report errors on unused parameters.

Report error when not all code paths in function return a value.

Report errors for fallthrough cases in switch statement.

Enables experimental support for ES7 decorators.

Enables experimental support for emitting type metadata for decorators.

Print names of files part of the compilation.

Print names of generated files part of the compilation.

Enable tracing of the name resolution process.

Show diagnostic information.

Show verbose diagnostic information.

This option gives you the chance to have TypeScript emit a v8 CPU profile during the compiler run. The CPU profile can provide insight into why your builds may be slow.

This option can only be used from the CLI via: --generateCpuProfile tsc-output.cpuprofile.

sh
npm run tsc --generateCpuProfile tsc-output.cpuprofile

This file can be opened in a chromium based browser like Chrome or Edge Developer in the CPU profiler section.

The locale used when displaying messages to the user (e.g. ‘en-us’)

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

This setting is useful if you’re using a transpiler other than TypeScript to generate your JavaScript.

Allowed Values: Any identifier or dotted identifier; default "React.createElement"

Changes the function called in .js files when compiling JSX Elements. The most common change is to use "h" or "preact.h" instead of the default "React.createElement" if using preact.

This is the same as Babel’s /** @jsx h */ directive.

Include modules imported with ‘.json’ extension

❌ Deprecated: Do not use this. Use [[outFile]] instead

The out option computes the final file location in a way that is not predictable or consistent. This option is retained for backward compatibility only.

[Deprecated] Use ‘—jsxFactory’ instead. Specify the object invoked for createElement when targeting ‘react’ JSX emit

[Deprecated] Use ‘—skipLibCheck’ instead. Skip type checking of default library declaration files.

❌ Deprecated: This option does nothing.

In prior versions of TypeScript, this controlled what encoding was used when reading text files from disk. Today, TypeScript assumes UTF-8 encoding, but will correctly detect UTF-16 (BE and LE) or UTF-8 BOMs.

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.

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

Do not truncate error messages.

Disables the automatic inclusion of any library files. If this option is set, lib is ignored.

🧙 This option is rarely used.

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 isn’t 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.

Do not emit declarations for code that has an ‘@internal’ annotation.

Disable size limitations on JavaScript projects.

When working with composite TypeScript projects, this option provides a way to go back to the pre-3.7 behavior where d.ts files were used to as the boundaries between modules. In 3.7 the source for truth is now your TypeScript files.

🧙‍ You shouldn’t need this

By default, when emitting a module file to a non-ES6 target, TypeScript emits a "use strict"; prologue at the top of the file. This setting disables that.

ts
// @showEmit
// @target: ES3
// @module: AMD
// @noImplicitUseStrict
export function fn() {}

ts
// @showEmit
// @target: ES3
// @module: AMD
export function fn() {}

Do not generate custom helper functions like ’__extends’ in compiled output.

Do not emit outputs if any errors were reported.

Do not erase const enum declarations in generated code.

Output directory for generated declaration files.

ts
function longest<T extends { length: number }>(a: T, b: T) {
  if (a.length >= b.length) {
    return a;
  } else {
    return b;
  }
}

//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

// longerArray is of type 'number[]'
const longerArray = longest([1, 2], [1, 2, 3]);
// longerString is of type 'string'
const longerString = longest("alice", "bob");
// Error! Numbers don't have a 'length' property
const notOK = longest(10, 100);
Argument of type '10' is not assignable to parameter of type '{ length: number; }'.2345Argument of type '10' is not assignable to parameter of type '{ length: number; }'.
const hello = longest("alice", "bob");
console.log(hello);

Skip type checking of declaration files.

Disables warnings about unused labels. Labels are very rare in JavaScript and typically indicate an attempt to write an object literal:

ts
// @allowUnusedLabels: false
function f(a: number) {
  // Forgot 'return' statement!
  if (a > 10) {
    m: 0;
  }
}

Disables warnings about unreachable code. These warnings are only about code which is provably unreachable due to syntactic construction, like the example below.

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

TypeScript doesn’t error on the basis of code which appears to be unreachable due to type analysis.

❌ Discouraged: This flag is provided for backward compatibility. Consider using @ts-ignore instead.

This disables reporting of excess property errors, such as the one shown in the following example

ts
type Point = { x: number; y: number };
const p: Point = { x: 1, y: 3, m: 10 };

❌ Discouraged: This flag is provided for backward compatibility. Consider using @ts-ignore instead.

This disables reporting of implicit any warnings when indexing into objects, such as shown in the following example

ts
const obj = { x: 10 };
console.log(obj["foo"]);

TypeScript follows the case sensitivity rules of the file system it’s running on. This can be problematic if some developers are working in a case-sensitive file system and others aren’t. If a file attempts to import fileManager.ts by specifying ./FileManager.ts the file will be found in a case-insensitive file system, but not on a case-sensitive file system.

When this option is set, TypeScript will issue an error if a program tries to include a file by a casing different from the casing on disk.

We recommend enabling this option in all projects.

The maximum dependency depth to search under node_modules and load JavaScript files.

Disable strict checking of generic signatures in function types.

This flag is used as a part of migrating to the upcoming standard version of how class fields works. TypeScript introduced class fields many years before it was ratified in TC39, where it had a different runtime behavior but the same syntax. This flag switches to the ECMA runtime behavior.

You can read more about the transition in the 3.7 release notes.

❌ Discouraged: This flag was provided for backward compatibility reasons and should not be enabled in new or maintained codebases.

This flag changes the keyof type operator to return string instead of string | number when applied to a type with a string index signature.

Whether to keep outdated console output in watch mode instead of clearing the screen.

Stylize errors and messages using color and context (experimental).