These settings help you ensure that TypeScript picks up the right files.
\nfilesSpecifies an allowlist of files to include in the program. An error occurs if any of the files can’t be found.
\n\njson{\n \"compilerOptions\": {},\n \"files\": [\n \"core.ts\",\n \"sys.ts\",\n \"types.ts\",\n \"scanner.ts\",\n \"parser.ts\",\n \"utilities.ts\",\n \"binder.ts\",\n \"checker.ts\",\n \"tsc.ts\"\n ]\n}
This is useful when you only have a small number of files and don’t need to use a glob to reference many files.\nIf you need that then use include.
| Flag | files \n | |
| Default |
|
includeSpecifies an array of filenames or patterns to include in the program.\nThese filenames are resolved relative to the directory containing the tsconfig.json file.
\njson{\n \"include\": [\"src/**/*\", \"tests/**/*\"]\n}
Which would include:
\n\n.\n├── scripts ⨯\n│ ├── lint.ts ⨯\n│ ├── update_deps.ts ⨯\n│ └── utils.ts ⨯\n├── src ✓\n│ ├── client ✓\n│ │ ├── index.ts ✓\n│ │ └── utils.ts ✓\n│ ├── server ✓\n│ │ └── index.ts ✓\n├── tests ✓\n│ ├── app.test.ts ✓\n│ ├── utils.ts ✓\n│ └── tests.d.ts ✓\n├── package.json\n├── tsconfig.json\n└── yarn.lock\ninclude 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 levelIf 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).
| Flag | include \n | |
| Default |
|
excludeSpecifies 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.\nA 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.
| Flag | exclude \n | |
| Default |
|
extendsThe value of extends is a string which contains a path to another configuration file to inherit from.\nThe 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.
\nIt’s worth noting that files, include and exclude from the inheriting config file overwrite those from the\nbase config file, and that circularity between configuration files is not allowed.
configs/base.json:
\njson{\n \"compilerOptions\": {\n \"noImplicitAny\": true,\n \"strictNullChecks\": true\n }\n}
tsconfig.json:
\njson{\n \"extends\": \"./configs/base\",\n \"files\": [\"main.ts\", \"supplemental.ts\"]\n}
tsconfig.nostrictnull.json:
\njson{\n \"extends\": \"./tsconfig\",\n \"compilerOptions\": {\n \"strictNullChecks\": false\n }\n}
| Flag | extends \n | |
| Default |
|
typeAcquisitionWhen you have a JavaScript project in your editor, TypeScript will provide types for your node_modules automatically using the DefinitelyTyped set of @types definitions.\nThis is called automatic type acquisition, and you can customize it using the typeAcquisition object in your configuration.
If you would like to disable or customize this feature, create a jsconfig.json in the root of your project:
\njson{\n \"typeAcquisition\": {\n \"enable\": false\n }\n}
If you have a specific module which should be included (but isn’t in node_modules):
\njson{\n \"typeAcquisition\": {\n \"include\": [\"jest\"]\n }\n}
If a module should not be automatically acquired, for example if the library is available in your node_modules but your team has agreed to not use it:
\njson{\n \"typeAcquisition\": {\n \"exclude\": [\"jquery\"]\n }\n}
| Flag | typeAcquisition \n | |
| Default |
|
referencesProject references are a way to structure your TypeScript programs into smaller pieces.\nUsing Project References can greatly improve build and editor interaction times, enforce logical separation between components, and organize your code in new and improved ways.
\nYou can read more about how references works in the Project References section of the handbook
\n| Flag | references \n | |
| Default |
|
These settings are used to define the runtime expectations of your project, how and where you want the JavaScript to be emitted and the level of integration you want with existing JavaScript code.
\nincrementalTells TypeScript to save information about the project graph from the last compilation to files stored on disk. This\ncreates a series of .tsbuildinfo files in the same folder as your compilation output. They are not used by your\nJavaScript at runtime and can be safely deleted. You can read more about the flag in the 3.4 release notes.
To control which folders you want to the files to be built to, use the config option tsBuildInfoFile.
| Flag | incremental \n | |
| Default |
| |
| Related | \n | |
| Released | \n |
targetModern browsers support all ES6 features, so ES6 is a good choice.\nYou might choose to set a lower target if your code is deployed to older environments, or a higher target if your code is guaranteed to run in newer environments.
The target setting changes which JS features are downleveled and which are left intact.\nFor example, an arrow function () => this will be turned into an equivalent function expression if target is ES5 or lower.
Changing target also changes the default value of lib.\nYou may “mix and match” target and lib settings as desired, but you could just set target for convenience.
If your are only working with Node.js, here are recommended target based off of the Node version:
| Name | \nSupported Target | \n
|---|---|
| Node 8 | \nES2017 | \n
| Node 10 | \nES2018 | \n
| Node 12 | \nES2019 | \n
These are based on node.green’s database of support.
\nThe special ESNext value refers to the highest version your TypeScript supports.\nThis setting should be used with caution, since it doesn’t mean the same thing between different TypeScript versions and can make upgrades less predictable.
| Flag | target \n | |
| Default |
| |
| Allowed |
| |
| Released | \n |
moduleSets the module system for the program. See the Modules chapter of the handbook for more information. You very likely want \"CommonJS\".
Here’s some example output for this file:
\n\nts// @filename: index.ts\nimport { valueOfPi } from \"./constants\";\n\nexport const twoPi = valueOfPi * 2;
CommonJS\njsconst constants_1 = require(\"./constants\");\nexports.twoPi = constants_1.valueOfPi * 2;
UMD\njs(function (factory) {\n if (typeof module === \"object\" && typeof module.exports === \"object\") {\n var v = factory(require, exports);\n if (v !== undefined) module.exports = v;\n }\n else if (typeof define === \"function\" && define.amd) {\n define([\"require\", \"exports\", \"./constants\"], factory);\n }\n})(function (require, exports) {\n \"use strict\";\n Object.defineProperty(exports, \"__esModule\", { value: true });\n const constants_1 = require(\"./constants\");\n exports.twoPi = constants_1.valueOfPi * 2;\n});
AMD\njsdefine([\"require\", \"exports\", \"./constants\"], function (require, exports, constants_1) {\n \"use strict\";\n Object.defineProperty(exports, \"__esModule\", { value: true });\n exports.twoPi = constants_1.valueOfPi * 2;\n});
System\njsSystem.register([\"./constants\"], function (exports_1, context_1) {\n \"use strict\";\n var constants_1, twoPi;\n var __moduleName = context_1 && context_1.id;\n return {\n setters: [\n function (constants_1_1) {\n constants_1 = constants_1_1;\n }\n ],\n execute: function () {\n exports_1(\"twoPi\", twoPi = constants_1.valueOfPi * 2);\n }\n };\n});
ESNext\njsimport { valueOfPi } from \"./constants\";\nexport const twoPi = valueOfPi * 2;
| Flag | module \n | |
| Allowed |
| |
| Released | \n |
libTypeScript 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).\nTypeScript 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:
\n\"dom\" type definitions| Name | \nContents | \n
|---|---|
ES5 | \nCore definitions for all ES3 and ES5 functionality | \n
ES2015 | \nAdditional APIs available in ES2015 (also known as ES6) - array.find, Promise, Proxy, Symbol, Map, Set, Reflect, etc. | \n
ES6 | \nAlias for “ES2015” | \n
ES2016 | \nAdditional APIs available in ES2016 - array.include, etc. | \n
ES7 | \nAlias for “ES2016” | \n
ES2017 | \nAdditional APIs available in ES2017 - Object.entries, Object.values, Atomics, SharedArrayBuffer, date.formatToParts, typed arrays, etc. | \n
ES2018 | \nAdditional APIs available in ES2018 - async iterables, promise.finally, Intl.PluralRules, rexexp.groups, etc. | \n
ES2019 | \nAdditional APIs available in ES2019 - array.flat, array.flatMap, Object.fromEntries, string.trimStart, string.trimEnd, etc. | \n
ES2020 | \nAdditional APIs available in ES2020 - string.matchAll, etc. | \n
ESNext | \nAdditional APIs available in ESNext - This changes as the JavaScript specification evolves | \n
DOM | \nDOM definitions - window, document, etc. | \n
WebWorker | \nAPIs available in WebWorker contexts | \n
ScriptHost | \nAPIs for the Windows Script Hosting System | \n
| Name | \n
|---|
DOM.Iterable | \n
ES2015.Core | \n
ES2015.Collection | \n
ES2015.Generator | \n
ES2015.Iterable | \n
ES2015.Promise | \n
ES2015.Proxy | \n
ES2015.Reflect | \n
ES2015.Symbol | \n
ES2015.Symbol.WellKnown | \n
ES2016.Array.Include | \n
ES2017.object | \n
ES2017.Intl | \n
ES2017.SharedMemory | \n
ES2017.String | \n
ES2017.TypedArrays | \n
ES2018.Intl | \n
ES2018.Promise | \n
ES2018.RegExp | \n
ES2019.Array | \n
ES2019.Full | \n
ES2019.Object | \n
ES2019.String | \n
ES2019.Symbol | \n
ES2020.Full | \n
ES2020.String | \n
ES2020.Symbol.wellknown | \n
ESNext.AsyncIterable | \n
ESNext.Array | \n
ESNext.Intl | \n
ESNext.Symbol | \n
This list may be out of date, you can see the full list in the TypeScript source code.
\n| Flag | lib \n | |
| Released | \n |
allowJsAllow JavaScript files to be imported inside your project, instead of just .ts and .tsx files. For example, this JS file:
\njs// @filename: card.js\nexport const defaultCardDeck = \"Heart\";
When imported into a TypeScript file will raise an error:
\n\nts// @filename: index.ts\nimport { defaultCardDeck } from \"./card\";\n\nconsole.log(defaultCardDeck);
Imports fine with allowJs enabled:
\nts// @filename: index.ts\nimport { defaultCardDeck } from \"./card\";\n\nconsole.log(defaultCardDeck);
This flag can be used as a way to incrementally add TypeScript files into JS projects by allowing the .ts and .tsx files to live along-side existing JavaScript files.
| Flag | allowJs \n | |
| Default |
| |
| Related | \n | |
| Released | \n |
checkJsWorks in tandem with allowJs. When checkJs is enabled then errors are reported in JavaScript files. This is\nthe equivalent of including // @ts-check at the top of all JavaScript files which are included in your project.
For example, this is incorrect JavaScript according to the parseFloat type definition which comes with TypeScript:
\njs// parseFloat only takes a string\nmodule.exports.pi = parseFloat(3.124);
When imported into a TypeScript module:
\n\nts// @filename: constants.js\nmodule.exports.pi = parseFloat(3.124);\n\n// @filename: index.ts\nimport { pi } from \"./constants\";\nconsole.log(pi);
You will not get any errors. However, if you turn on checkJs then you will get error messages from the JavaScript file.
\nts// @filename: constants.js\nArgument of type '3.124' is not assignable to parameter of type 'string'.2345Argument of type '3.124' is not assignable to parameter of type 'string'.module.exports.pi = parseFloat(3.124);\n\n// @filename: index.ts\nimport { pi } from \"./constants\";\nconsole.log(pi);
| Flag | checkJs \n | |
| Default |
| |
| Related | \n |
jsxControls how JSX constructs are emitted in JavaScript files.\nThis only affects output of JS files that started in .tsx files.
preserve: Emit .jsx files with the JSX unchangedreact: Emit .js files with JSX changed to the equivalent React.createElement callsreact-native: Emit .js files with the JSX unchanged| Flag | jsx \n | |
| Default |
| |
| Allowed |
| |
| Released | \n |
declarationGenerate d.ts files for every TypeScript or JavaScript file inside your project.\nThese d.ts files are type definition files which describe the external API of your module.\nWith d.ts files, tools like TypeScript can provide intellisense and accurate types for un-typed code.
When declaration is set to true, running the compiler with this TypeScript code:
\ntsexport let helloWorld let helloWorld: string= \"hi\";
Will generate an index.js file like this:
\njsexport let helloWorld = \"hi\";
With a corresponding helloWorld.d.ts:
\ntsexport declare let helloWorld: string;
When working with d.ts files for JavaScript files you may want to use emitDeclarationOnly or use outDir to ensure that the JavaScript files are not overwritten.
| Flag | declaration \n | |
| Default | True when TS \n | |
| Related | \n | |
| Released | \n |
declarationMapGenerates a source map for .d.ts files which map back to the original .ts source file.\nThis 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.
\n| Flag | declarationMap \n | |
| Default |
| |
| Released | \n |
sourceMapEnables the generation of sourcemap files.\nThese files allow debuggers and other tools to display the original TypeScript source code when actually working with the emitted JavaScript files.\nSource 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 to external tools, for example:
\nts// helloWorld.ts\nexport declare const helloWorld = \"hi\";
Compiling with sourceMap set to true creates the following JavaScript file:
\njs// helloWorld.js\n\"use strict\";\nObject.defineProperty(exports, \"__esModule\", { value: true });\nexports.helloWorld = \"hi\";\n//# sourceMappingURL=// helloWorld.js.map
And this also generates this json map:
\n\njson// helloWorld.js.map\n{\n \"version\": 3,\n \"file\": \"ex.js\",\n \"sourceRoot\": \"\",\n \"sources\": [\"../ex.ts\"],\n \"names\": [],\n \"mappings\": \";;AAAa,QAAA,UAAU,GAAG,IAAI,CAAA\"\n}
| Flag | sourceMap \n | |
| Default |
|
outFileIf specified, all global (non-module) files will be concatenated into the single output file specified.
\nIf 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.\nThis option cannot be used to bundle CommonJS or ES6 modules.
| Flag | outFile \n | |
| Default |
| |
| Related | \n | |
| Released | \n |
outDirIf specified, .js (as well as .d.ts, .js.map, etc.) files will be emitted into this directory.\nThe 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:
\nsh$ tsc\n\nexample\n├── index.js\n└── index.ts
With a tsconfig.json like this:
\njson{\n \"compilerOptions\": {\n \"outDir\": \"dist\"\n }\n}
Running tsc with these settings moves the files into the specified dist folder:
\nsh$ tsc\n\nexample\n├── dist\n│ └── index.js\n├── index.ts\n└── tsconfig.json
| Flag | outDir \n | |
| Default |
| |
| Related | \n |
rootDirDefault: 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.
\nFor example, let’s say you have some input files:
\nMyProj\n├── tsconfig.json\n├── core\n│ ├── a.ts\n│ ├── b.ts\n│ ├── sub\n│ │ ├── c.ts\n├── types.d.ts\nThe 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\n├── dist\n│ ├── a.ts\n│ ├── b.ts\n│ ├── sub\n│ │ ├── c.ts\nHowever, you may have intended for core to be part of the output directory structure.\nBy setting rootDir: \".\" in tsconfig.json, TypeScript would write this tree:
MyProj\n├── dist\n│ ├── core\n│ │ ├── a.js\n│ │ ├── b.js\n│ │ ├── sub\n│ │ │ ├── c.js\nImportantly, rootDir does not affect which files become part of the compilation.\nIt 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.\nFor 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:
\nMyProj\n├── tsconfig.json\n├── core\n│ ├── a.ts\n│ ├── b.ts\n├── helpers.ts\nIt 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).
| Flag | rootDir \n | |
| Default | Computed from the list of input files \n | |
| Released | \n |
compositeThe composite option enforces certain constraints which make it possible for build tools (including TypeScript\nitself, under --build mode) to quickly determine if a project has been built yet.
When this setting is on:
\nrootDir setting, if not explicitly set, defaults to the directory containing the tsconfig.json file.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 trueYou can find documentation on TypeScript projects in the handbook.
\n| Flag | composite \n | |
| Default |
| |
| Related | \n | |
| Released | \n |
tsBuildInfoFileThis setting lets you specify a file for storing incremental compilation information as a part of composite projects which enables faster\nbuilding of larger TypeScript codebases. You can read more about composite projects in the handbook.
\nThis option offers a way to configure the place where TypeScript keeps track of the files it stores on the disk to\nindicate a project’s build state — by default, they are in the same folder as your emitted JavaScript.
\n| Flag | tsBuildInfoFile \n | |
| Default | .tsbuildinfo \n | |
| Released | \n |
removeCommentsStrips all comments from TypeScript files when converting into JavaScript. Defaults to false.
For example, this is a TypeScript file which has a JSDoc comment:
\n\nts/** The translation of 'Hello world' into Portuguese */\nexport const helloWorldPTBR = \"Olá Mundo\";
When removeComments is set to true:
\njsexport const helloWorldPTBR = \"Olá Mundo\";
Without setting removeComments or having it as false:
\njs/** The translation of 'Hello world' into Portuguese */\nexport const helloWorldPTBR = \"Olá Mundo\";
This means that your comments will show up in the JavaScript code.
\n| Flag | removeComments \n | |
| Default |
|
noEmitDo not emit compiler output files like JavaScript source code, source-maps or declarations.
\nThis makes room for another tool like Babel, or swc to handle converting the TypeScript file to a file which can run inside a JavaScript environment.
\nYou can then use TypeScript as a tool for providing editor integration, and as a source code type-checker.
\n| Flag | noEmit \n | |
| Default |
|
importHelpersFor certain downleveling operations, TypeScript uses some helper code for operations like extending class, spreading arrays or objects, and async operations.\nBy default, these helpers are inserted into files which use them.\nThis can result in code duplication if the same helper is used in many different modules.
\nIf the importHelpers flag is on, these helper functions are instead imported from the tslib module.\nYou will need to ensure that the tslib module is able to be imported at runtime.\nThis only affects modules; global script files will not attempt to import modules.
For example, with this TypeScript:
\n\ntsexport function fn(arr: number[]) {\n const arr2 = [1, ...arr];\n}
Turning on downlevelIteration and importHelpers is still false:
\njsvar __read = (this && this.__read) || function (o, n) {\n var m = typeof Symbol === \"function\" && o[Symbol.iterator];\n if (!m) return o;\n var i = m.call(o), r, ar = [], e;\n try {\n while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);\n }\n catch (error) { e = { error: error }; }\n finally {\n try {\n if (r && !r.done && (m = i[\"return\"])) m.call(i);\n }\n finally { if (e) throw e.error; }\n }\n return ar;\n};\nvar __spread = (this && this.__spread) || function () {\n for (var ar = [], i = 0; i < arguments.length; i++) ar = ar.concat(__read(arguments[i]));\n return ar;\n};\nexport function fn(arr) {\n var arr2 = __spread([1], arr);\n}
Then turning on both downlevelIteration and importHelpers:
\njsimport { __read, __spread } from \"tslib\";\nexport function fn(arr) {\n var arr2 = __spread([1], arr);\n}
You can use noEmitHelpers when you provide your own implementations of these functions.
| Flag | importHelpers \n | |
| Default |
| |
| Related | \n |
downlevelIterationDownleveling is TypeScript’s term for transpiling to an older version of JavaScript.\nThis flag is to enable support for a more accurate implementation of how modern JavaScript iterates through new concepts in older JavaScript runtimes.
\nECMAScript 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.\n--downlevelIteration allows for these iteration primitives to be used more accurately in ES5 environments if a Symbol.iterator implementation is present.
for / ofWithout downlevelIteration on, a for / of loop on any object is downleveled to a traditional for loop:
\njs\"use strict\";\nvar str = \"Hello!\";\nfor (var _i = 0, str_1 = str; _i < str_1.length; _i++) {\n var s = str_1[_i];\n console.log(s);\n}
This is often what people expect, but it’s not 100% compliant with ECMAScript 6 behavior.\nCertain strings, such as emoji (😜), have a .length of 2 (or even more!), but should iterate as 1 unit in a for-of loop.\nSee 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).\nIf this implementation is missing, you’ll fall back to index-based iteration.
\njs\"use strict\";\nvar __values = (this && this.__values) || function(o) {\n var s = typeof Symbol === \"function\" && Symbol.iterator, m = s && o[s], i = 0;\n if (m) return m.call(o);\n if (o && typeof o.length === \"number\") return {\n next: function () {\n if (o && i >= o.length) o = void 0;\n return { value: o && o[i++], done: !o };\n }\n };\n throw new TypeError(s ? \"Object is not iterable.\" : \"Symbol.iterator is not defined.\");\n};\nvar e_1, _a;\nvar str = \"Hello!\";\ntry {\n for (var str_1 = __values(str), str_1_1 = str_1.next(); !str_1_1.done; str_1_1 = str_1.next()) {\n var s = str_1_1.value;\n console.log(s);\n }\n}\ncatch (e_1_1) { e_1 = { error: e_1_1 }; }\nfinally {\n try {\n if (str_1_1 && !str_1_1.done && (_a = str_1.return)) _a.call(str_1);\n }\n finally { if (e_1) throw e_1.error; }\n}
\n\n\n\nNote: enabling
\ndownlevelIterationdoes not improve compliance ifSymbol.iteratoris not present in the runtime.
This is an array spread:
\n\njs// Make a new array who elements are 1 followed by the elements of arr2\nconst arr = [1, ...arr2];
Based on the description, it sounds easy to downlevel to ES5:
\n\njs// The same, right?\nconst arr = [1].concat(arr2);
However, this is observably different in certain rare cases.\nFor 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:
\njs// Make an array where the '1' element is missing\nlet missing = [0, , 1];\nlet spreaded = [...missing];\nlet concated = [].concat(missing);\n\n// true\n\"1\" in spreaded;\n// false\n\"1\" in concated;
Just as with for / of, downlevelIteration will use Symbol.iterator (if present) to more accurately emulate ES 6 behavior.
| Flag | downlevelIteration \n | |
| Default |
| |
| Released | \n |
isolatedModulesWhile 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.\nHowever, other transpilers only operate on a single file at a time, which means they can’t apply code transforms that depend on understanding the full type system.\nThis restriction also applies to TypeScript’s ts.transpileModule API which is used by some build tools.
These limitations can cause runtime problems with some TypeScript features like const enums and namespaces.\nSetting 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.
\nSome examples of code which does not work when isolatedModules is enabled.
In TypeScript, you can import a type and then subsequently export it:
\n\ntsimport { someType,import someType someFunction import someFunction} from \"someModule\";\n\nsomeFunction(import someFunction);\n\nexport { someType,export someType someFunction export someFunction};
Because there’s no value for someType, the emitted export will not try to export it (this would be a runtime error in JavaScript):
\njsexport { 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, all implementation files must be modules (which means it has some form of import/export). An error occurs if any file isn’t a module:
\ntsfn(function fn(): void) {}\nAll files must be modules when the '--isolatedModules' flag is provided.1208All files must be modules when the '--isolatedModules' flag is provided.
This restriction doesn’t apply to .d.ts files
const enum membersIn TypeScript, when you reference a const enum member, the reference is replaced by its actual value in the emitted JavaScript. Changing this TypeScript:
\ntsdeclare const enum Numbers const enum Numbers\n Zero (enum member) Numbers.Zero = 0= 0,\n One (enum member) Numbers.One = 1= 1\n}\nconsole.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): voidNumbers.const enum NumbersZero (enum member) Numbers.Zero = 0+ Numbers.const enum NumbersOne)(enum member) Numbers.One = 1
To this JavaScript:
\n\njs\"use strict\";\nconsole.log(0 + 1);
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 are no Numbers object at runtime).\nBecause of this, when isolatedModules is set, it is an error to reference an ambient const enum member.
| Flag | isolatedModules \n | |
| Default |
|
We recommend using the option strict to opt-in to every possible improvement as they are built.
TypeScript supports a wide spectrum of JavaScript patterns and defaults to allowing for quite a lot of flexibility in accommodating these styles.\nOften the safety and potential scalability of a codebase can be at odds with some of these techniques.
\nBecause of the variety of supported JavaScript, upgrading to a new version of TypeScript can uncover two types of errors:
\nTypeScript will usually add a compiler flag for the latter set of errors, and by default these are not enabled.
\nstrictThe strict flag enables a wide range of type checking behavior that results in stronger guarantees of program correctness.\nTurning this on is equivalent to enabling all of the strict mode family options, which are outlined below.\nYou 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.\nWhen appropriate and possible, a corresponding flag will be added to disable that behavior.
\n| Flag | strict \n | |
| Recommended | True \n | |
| Default |
| |
| Related |
| |
| Released | \n |
noImplicitAnyIn 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:
\n\ntsfunction fn(function fn(s: any): voids)(parameter) s: any {\n // No error?\n console.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): voids.(parameter) s: anysubtr(any3));\n}\nfn(function fn(s: any): void42);
Turning on noImplicitAny however TypeScript will issue an error whenever it would have inferred any:
\ntsfunction fn(function fn(s: any): voids)(parameter) s: any {\nParameter 's' implicitly has an 'any' type.7006Parameter 's' implicitly has an 'any' type. console.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): voids.(parameter) s: anysubtr(any3));\n}
| Flag | noImplicitAny \n | |
| Recommended | True \n | |
| Default |
|
strictNullChecksWhen strictNullChecks is false, null and undefined are effectively ignored by the language.\nThis 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\nwrite code as though it will:
\ntsdeclare const loggedInUsername:const loggedInUsername: string string;\n\nconst users const users: { name: string; age: number; }[]= [\n { name:(property) name: string\"Oby\", age:(property) age: number12 },\n { name:(property) name: string\"Heera\", age:(property) age: number32 }\n];\n\nconst loggedInUser const loggedInUser: { name: string; age: number; }= users.const users: { name: string; age: number; }[]find((method) Array<{ name: string; age: number; }>.find(predicate: (value: { name: string; age: number; }, index: number, obj: { name: string; age: number; }[]) => unknown, thisArg?: any): { name: string; age: number; } (+1 overload)u (parameter) u: { name: string; age: number; }=> u.(parameter) u: { name: string; age: number; }name (property) name: string=== loggedInUsername)const loggedInUsername: string\nconsole.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): voidloggedInUser.const loggedInUser: { name: string; age: number; }age)(property) age: number
Setting strictNullChecks to true will raise an error that you have not made a guarantee that the loggedInUser exists before trying to use it.
\ntsdeclare const loggedInUsername:const loggedInUsername: string string;\n\nconst users const users: { name: string; age: number; }[]= [\n { name:(property) name: string\"Oby\", age:(property) age: number12 },\n { name:(property) name: string\"Heera\", age:(property) age: number32 }\n];\n\nconst loggedInUser const loggedInUser: { name: string; age: number; } | undefined= users.const users: { name: string; age: number; }[]find((method) Array<{ name: string; age: number; }>.find(predicate: (value: { name: string; age: number; }, index: number, obj: { name: string; age: number; }[]) => unknown, thisArg?: any): { name: string; age: number; } | undefined (+1 overload)u (parameter) u: { name: string; age: number; }=> u.(parameter) u: { name: string; age: number; }name (property) name: string=== loggedInUsername)const loggedInUsername: string\nconsole.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): voidloggedInUser.const loggedInUser: { name: string; age: number; } | undefinedage)(property) age: number\nObject is possibly 'undefined'.2532Object is possibly 'undefined'.
The second example failed because the array’s find function looks a bit like this simplification:
\nts// When strictNullChecks: true\ntype Array = {\n find(predicate: (value: any, index: number) => boolean): S | undefined;\n};\n\n// When strictNullChecks: false the undefined is removed from the type system,\n// allowing you to write code which assumes it always found a result\ntype Array = {\n find(predicate: (value: any, index: number) => boolean): S;\n};
| Flag | strictNullChecks \n | |
| Recommended | True \n | |
| Default |
| |
| Released | \n |
strictFunctionTypesWhen enabled, this flag causes functions parameters to be checked more correctly.
\nHere’s a basic example with strictFunctionTypes off:
\ntsfunction fn(function fn(x: string): voidx:(parameter) x: string string) {\n console.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): void\"Hello, \" + x.(parameter) x: stringtoLowerCase((method) String.toLowerCase(): string));\n}\n\ntype StringOrNumberFunc type StringOrNumberFunc = (ns: string | number) => void= (ns:(parameter) ns: string | number string | number) => void;\n\n// Unsafe assignment\nlet func:let func: StringOrNumberFunc StringOrNumberFunc type StringOrNumberFunc = (ns: string | number) => void= fn;function fn(x: string): void\n// Unsafe call - will crash\nfunc(let func: (ns: string | number) => void10);
With strictFunctionTypes on, the error is correctly detected:
\ntsfunction fn(function fn(x: string): voidx:(parameter) x: string string) {\n console.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): void\"Hello, \" + x.(parameter) x: stringtoLowerCase((method) String.toLowerCase(): string));\n}\n\ntype StringOrNumberFunc type StringOrNumberFunc = (ns: string | number) => void= (ns:(parameter) ns: string | number string | number) => void;\n\n// Unsafe assignment is prevented\nlet func:let func: StringOrNumberFunc StringOrNumberFunc type StringOrNumberFunc = (ns: string | number) => void= fn;function fn(x: string): void\nType '(x: string) => void' is not assignable to type 'StringOrNumberFunc'.\n Types of parameters 'x' and 'ns' are incompatible.\n Type 'string | number' is not assignable to type 'string'.\n Type 'number' is not assignable to type 'string'.2322Type '(x: string) => void' is not assignable to type 'StringOrNumberFunc'.\n Types of parameters 'x' and 'ns' are incompatible.\n Type 'string | number' is not assignable to type 'string'.\n Type 'number' is not assignable to type 'string'.
During development of this feature, we discovered a large number of inherently unsafe class hierarchies, including some in the DOM.\nBecause of this, the setting only applies to functions written in function syntax, not to those in method syntax:
\n\ntstype Methodish type Methodish = { func(x: string | number): void; }= {\n func((method) func(x: string | number): voidx:(parameter) x: string | number string | number): void;\n};\n\nfunction fn(function fn(x: string): voidx:(parameter) x: string string) {\n console.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): void\"Hello, \" + x.(parameter) x: stringtoLowerCase((method) String.toLowerCase(): string));\n}\n\n// Ultimately an unsafe assignment, but not detected\nconst m:const m: Methodish Methodish type Methodish = { func(x: string | number): void; }= {\n func:(method) func(x: string | number): void fnfunction fn(x: string): void\n};\nm.const m: Methodishfunc((method) func(x: string | number): void10);
| Flag | strictFunctionTypes \n | |
| Recommended | True \n | |
| Default |
| |
| Released | \n |
strictBindCallApplyWhen set, TypeScript will check that the built-in methods of functions call, bind, and apply are invoked with correct argument for the underlying function:
\nts// With strictBindCallApply on\nfunction fn(function fn(x: string): numberx:(parameter) x: string string) {\n return parseInt(function parseInt(s: string, radix?: number | undefined): numberx)(parameter) x: string\n}\n\nconst n1 const n1: number= fn.function fn(x: string): numbercall((method) CallableFunction.call<undefined, [string], number>(this: (this: undefined, args_0: string) => number, thisArg: undefined, args_0: string): numberundefinedvar undefined, \"10\");\n\nconst n2 const n2: number= fn.function fn(x: string): numbercall((method) CallableFunction.call<undefined, [string], number>(this: (this: undefined, x: string) => number, thisArg: undefined, x: string): numberundefinedvar undefined, false);\nArgument of type 'false' is not assignable to parameter of type 'string'.2345Argument of type 'false' is not assignable to parameter of type 'string'.
Otherwise, these functions accept any arguments and will return any:
\nts// With strictBindCallApply off\nfunction fn(function fn(x: string): numberx:(parameter) x: string string) {\n return parseInt(function parseInt(s: string, radix?: number | undefined): numberx)(parameter) x: string\n}\n\n// Note: No error; return type is 'any'\nconst n const n: any= fn.function fn(x: string): numbercall((method) Function.call(this: Function, thisArg: any, ...argArray: any[]): anyundefinedvar undefined, false);
| Flag | strictBindCallApply \n | |
| Recommended | True \n | |
| Default |
| |
| Released | \n |
strictPropertyInitializationWhen set to true, TypeScript will raise an error when a class property was declared but not set in the constructor.
\n\ntsclass UserAccount class UserAccount\n name:(property) UserAccount.name: string string;\n accountType (property) UserAccount.accountType: string= \"user\";\n\n email:(property) UserAccount.email: string string;\nProperty '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:(property) UserAccount.address: string | undefined string | undefined;\n\n constructor(name:(parameter) name: string string) {\n this.name (property) UserAccount.name: string= name;(parameter) name: string\n // Note that this.email is not set\n }\n}
In the above case:
\nthis.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.| Flag | strictPropertyInitialization \n | |
| Default |
| |
| Released | \n |
noImplicitThisRaise error on ‘this’ expressions with an implied ‘any’ type.
\nFor example, the class below returns a function which tries to access this.width and this.height – but the context\nfor this inside the function inside getAreaFunction is not the instance of the Rectangle.
\ntsclass Rectangle class Rectangle\n width:(property) Rectangle.width: number number;\n height:(property) Rectangle.height: number number;\n\n constructor(width:(parameter) width: number number, height:(parameter) height: number number) {\n this.width (property) Rectangle.width: number= width;(parameter) width: number\n this.height (property) Rectangle.height: number= height;(parameter) height: number\n }\n\n getAreaFunction((method) Rectangle.getAreaFunction(): () => number) {\n return function() {\n return this.width any* this.height;any\n'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. };\n }\n}
| Flag | noImplicitThis \n | |
| Recommended | True \n | |
| Default |
| |
| Released | \n |
alwaysStrictEnsures that your files are parsed in the ECMAScript strict mode, and emit “use strict” for each source file.
\nECMAScript 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.
\n| Flag | alwaysStrict \n | |
| Default |
| |
| Released | \n |
moduleResolutionSpecify module resolution strategy: ‘node’ (Node.js) or ‘classic’ (TypeScript pre-1.6). You probably won’t need to use this.
\n| Flag | moduleResolution \n | |
| Status | Deprecated \n | |
| Status | Deprecated \n |
baseUrlLets you set a base directory to resolve non-absolute module names.
\nYou can define a root folder where you can do absolute file resolution. E.g.
\nbaseUrl\n├── ex.ts\n├── hello\n│ └── world.ts\n└── tsconfig.json\nWith \"baseUrl\": \"./\" inside this project TypeScript will look for files starting at the same folder as the tsconfig.json.
\ntsimport { helloWorld } from \"hello/world\";\n\nconsole.log(helloWorld);
If you get tired of imports always looking like \"../\" or \"./\". Or needing\nto change as you move files, this is a great way to fix that.
| Flag | baseUrl \n |
pathsA series of entries which re-map imports to lookup locations relative to the baseUrl, there is a larger coverage of paths in the handbook.
paths lets you declare how TypeScript should resolve an import in your require/imports.
\njson{\n \"compilerOptions\": {\n \"baseUrl\": \".\", // this must be specified if \"paths\" is specified.\n \"paths\": {\n \"jquery\": [\"node_modules/jquery/dist/jquery\"] // this mapping is relative to \"baseUrl\"\n }\n }\n}
This would allow you to be able to write import \"jquery\", and get all of the correct typing locally.
\njson{\n \"compilerOptions\": {\n \"baseUrl\": \"src\",\n \"paths\": {\n \"app/*\": [\"app/*\"],\n \"config/*\": [\"app/_config/*\"],\n \"environment/*\": [\"environments/*\"],\n \"shared/*\": [\"app/_shared/*\"],\n \"helpers/*\": [\"helpers/*\"],\n \"tests/*\": [\"tests/*\"]\n },\n}
In this case, you can tell the TypeScript file resolver to support a number of custom prefixes to find code.\nThis pattern can be used to avoid long relative paths within your codebase.
\n| Flag | paths \n |
rootDirsUsing rootDirs, you can inform the compiler that there are many “virtual” directories acting as a single root.\nThis allows the compiler to resolve relative module imports within these “virtual” directories, as if they were merged in to one directory.
For example:
\n src\n └── views\n └── view1.ts (can import \"./template1\", \"./view2`)\n └── view2.ts (can import \"./template1\", \"./view1`)\n\n generated\n └── templates\n └── views\n └── template1.ts (can import \"./view1\", \"./view2\")\n\njson{\n \"compilerOptions\": {\n \"rootDirs\": [\"src/views\", \"generated/templates/views\"]\n }\n}
This does not affect how TypeScript emits JavaScript, it only emulates the assumption that they will be able to\nwork via those relative paths at runtime.
\n| Flag | rootDirs \n | |
| Released | \n |
typeRootsBy default all visible ”@types” packages are included in your compilation.\nPackages in node_modules/@types of any enclosing folder are considered visible.\nFor example, that means packages within ./node_modules/@types/, ../node_modules/@types/, ../../node_modules/@types/, and so on.
If typeRoots is specified, only packages under typeRoots will be included. For example:
\njson{\n \"compilerOptions\": {\n \"typeRoots\": [\"./typings\", \"./vendor/types\"]\n }\n}
This config file will include all packages under ./typings and ./vendor/types, and no packages from ./node_modules/@types.\nAll paths are relative to the tsconfig.json.
| Flag | typeRoots \n | |
| Related | \n |
typesBy default all visible ”@types” packages are included in your compilation.\nPackages in node_modules/@types of any enclosing folder are considered visible.\nFor example, that means packages within ./node_modules/@types/, ../node_modules/@types/, ../../node_modules/@types/, and so on.
If types is specified, only packages listed will be included. For instance:
\njson{\n \"compilerOptions\": {\n \"types\": [\"node\", \"lodash\", \"express\"]\n }\n}
This tsconfig.json file will only include ./node_modules/@types/node, ./node_modules/@types/lodash and ./node_modules/@types/express.\nOther packages under node_modules/@types/* will not be included.
This feature differs from typeRoots in that it is about specifying only the exact types you want included, whereas typeRoots supports saying you want particular folders.
| Flag | types \n | |
| Related | \n |
allowSyntheticDefaultImportsWhen set to true, allowSyntheticDefaultImports let’s you write an import like:
\ntsimport React from \"react\";
instead of:
\n\ntsimport * as React from \"react\";
When the module does not specify a default export.
\nThis does not affect the JavaScript emitted by TypeScript, it only for the type checking.\nThis option brings the behavior of TypeScript in-line with Babel, where extra code is emitted to make using a default export of a module more ergonomic.
\n| Flag | allowSyntheticDefaultImports \n | |
| Default | module === \"system\" or esModuleInterop \n | |
| Related | \n | |
| Released | \n |
esModuleInteropEnables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports.
\nTypeScript adheres to the EcmaScript standard for modules, which means that a file with exports would have to specifically\ninclude a default export in order to support syntax like import React from \"react\".\nThis export pattern is rare in modules for CommonJS. For example, without esModuleInterop as true:
\nts// @filename: utilFunctions.js\nconst getStringLength = str => str.length;\n\nports =anymodule.module export= (property) export=: { getStringLength: (str: any) => any; }exports = {\nStringLemodule export= (property) export=: { getStringLength: (str: any) => any; }ngth\n};\n\n// @filename: index.ts\nimport utils from \"./utilFunctions\";\n\nconst count = utils.getStringLength(\"Check JS\");
This won’t work because there isn’t a default object which you can import. Even though it feels like it should.\nFor convenience, transpilers like Babel will automatically create a default if one isn’t created. Making the module look a bit more like:
\njs// @filename: utilFunctions.js\nconst getStringLength = str => str.length;\nconst allFunctions = {\n getStringLength\n};\n\nmodule.exports = allFunctions;
Turning on this compiler flag will also enable allowSyntheticDefaultImports.
| Flag | esModuleInterop \n | |
| Default |
| |
| Related | \n | |
| Released | \n |
preserveSymlinksThis is to reflect the same flag in Node.js; which does not resolve the real path of symlinks.
\nThis flag also exhibits the opposite behavior to Webpack’s resolve.symlinks option (i.e. setting TypeScript’s preserveSymlinks to true parallels setting Webpack’s resolve.symlinks to false, and vice-versa).
With this enabled, references to modules and packages (e.g. imports and /// <reference type=\"...\" /> directives) are all resolved relative to the location of the symbolic link file, rather than relative to the path that the symbolic link resolves to.
| Flag | preserveSymlinks \n | |
| Default |
|
allowUmdGlobalAccessWhen set to true, allowUmdGlobalAccess lets you access UMD exports as globals from inside module files. A module file is a file that has imports and/or exports. Without this flag, using an export from a UMD module requires an import declaration.
An example use case for this flag would be a web project where you know the particular library (like jQuery or Lodash) will always be available at runtime, but you can’t access it with an import.
\n| Flag | allowUmdGlobalAccess \n | |
| Default |
| |
| Released | \n |
In order to provide rich debugging tools and crash reports which make sense to developers, TypeScript supports\nemitting additional files which conform to the JavaScript Source Map standards.
\nThese are emitted as .map files which live alongside the file they represent.
sourceRootSpecify the location where a debugger should locate TypeScript files instead of relative source locations.\nThis string is treated verbatim inside the source-map where you can use a path or a URL:
\n\njson{\n \"compilerOptions\": {\n \"sourceMap\": true,\n \"sourceRoot\": \"https://my-website.com/debug/source/\"\n }\n}
Would declare that index.js will have a source file at https://my-website.com/debug/source/index.ts.
| Flag | sourceRoot \n |
mapRootSpecify the location where debugger should locate map files instead of generated locations.\nThis string is treated verbatim inside the source-map, for example:
\n\njson{\n \"compilerOptions\": {\n \"sourceMap\": true,\n \"mapRoot\": \"https://my-website.com/debug/sourcemaps/\"\n }\n}
Would declare that index.js will have sourcemaps at https://my-website.com/debug/sourcemaps/index.js.map.
| Flag | mapRoot \n |
inlineSourceMapWhen set, instead of writing out a .js.map file to provide source maps, TypeScript will embed the source map content in the .js files.\nAlthough this results in larger JS files, it can be convenient in some scenarios.\nFor 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:
\n\ntsconst helloWorld = \"hi\";\nconsole.log(helloWorld);
Converts to this JavaScript:
\n\njs\"use strict\";\nconst helloWorld = \"hi\";\nconsole.log(helloWorld);
Then enable building it with inlineSourceMap enabled there is a comment at the bottom of the file which includes\na source-map for the file.
\njs\"use strict\";\nconst helloWorld = \"hi\";\nconsole.log(helloWorld);\n//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyJpbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUEsTUFBTSxVQUFVLEdBQUcsSUFBSSxDQUFDO0FBQ3hCLE9BQU8sQ0FBQyxHQUFHLENBQUMsVUFBVSxDQUFDLENBQUMifQ==
| Flag | inlineSourceMap \n | |
| Default |
| |
| Released | \n |
inlineSourcesWhen set, TypeScript will include the original content of the .ts file as an embedded string in the source map.\nThis is often useful in the same cases as inlineSourceMap.
Requires either sourceMap or inlineSourceMap to be set.
For example, with this TypeScript:
\n\ntsconst helloWorld const helloWorld: "hi"= \"hi\";\nconsole.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): voidhelloWorld)const helloWorld: "hi"
By default converts to this JavaScript:
\n\njs\"use strict\";\nconst helloWorld = \"hi\";\nconsole.log(helloWorld);
Then enable building it with inlineSources and inlineSourceMap enabled there is a comment at the bottom of the file which includes\na source-map for the file.\nNote that the end is different from the example in inlineSourceMap because the source-map now contains the original source code also.
\njs\"use strict\";\nconst helloWorld = \"hi\";\nconsole.log(helloWorld);\n//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyJpbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUEsTUFBTSxVQUFVLEdBQUcsSUFBSSxDQUFDO0FBQ3hCLE9BQU8sQ0FBQyxHQUFHLENBQUMsVUFBVSxDQUFDLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJjb25zdCBoZWxsb1dvcmxkID0gXCJoaVwiO1xuY29uc29sZS5sb2coaGVsbG9Xb3JsZCk7Il19
| Flag | inlineSources \n | |
| Default |
| |
| Released | \n |
A collection of extra checks, which somewhat cross the boundaries of compiler vs linter. You may prefer to use a tool like eslint over these options if you are looking for more in-depth rules.
\nnoUnusedLocalsReport errors on unused local variables.
\n\ntsconst createKeyboard const createKeyboard: (modelID: number) => { type: string; modelID: number; }= (modelID:(parameter) modelID: number number) => {\n const defaultModelID const defaultModelID: 23= 23;\n'defaultModelID' is declared but its value is never read.6133'defaultModelID' is declared but its value is never read. return { type:(property) type: string\"keyboard\", modelID (property) modelID: number};\n};
| Flag | noUnusedLocals \n | |
| Default |
| |
| Released | \n |
noUnusedParametersReport errors on unused parameters in functions.
\n\ntsconst createDefaultKeyboard const createDefaultKeyboard: (modelID: number) => { type: string; modelID: number; }= (modelID:(parameter) modelID: number number) => {\n'modelID' is declared but its value is never read.6133'modelID' is declared but its value is never read. const defaultModelID const defaultModelID: 23= 23;\n return { type:(property) type: string\"keyboard\", modelID:(property) modelID: number defaultModelID const defaultModelID: 23};\n};
| Flag | noUnusedParameters \n | |
| Default |
| |
| Released | \n |
noImplicitReturnsWhen enabled, TypeScript will check all code paths in a function to ensure they return a value.
\n\ntsfunction lookupHeadphonesManufacturer(function lookupHeadphonesManufacturer(color: "blue" | "black"): stringcolor:(parameter) color: "blue" | "black"\"blue\" | \"black\"): string \nFunction 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 (parameter) color: "blue" | "black"=== \"blue\") {\n return \"beats\";\n } else {\n \"bose\";\n }\n}
| Flag | noImplicitReturns \n | |
| Default |
| |
| Released | \n |
noFallthroughCasesInSwitchReport errors for fallthrough cases in switch statements.\nEnsures that any non-empty case inside a switch statement includes either break or return.\nThis means you won’t accidentally ship a case fallthrough bug.
\ntsconst a:const a: number number = 6;\n\nswitch (a)const a: number {\n case 0:\nFallthrough case in switch.7029Fallthrough case in switch. console.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): void\"even\");\n case 1:\n console.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): void\"odd\");\n break;\n}
| Flag | noFallthroughCasesInSwitch \n | |
| Default |
| |
| Released | \n |
TypeScript strives to only include features which are confirmed to be added into the JavaScript language.
\nThere have been cases where a feature is compelling enough to be an exception to that rule, and these live as experimental compiler flags.\nIt is possible that a version of these features may be different when/if they are added to the JavaScript language, and thus are considered risky.
\nexperimentalDecoratorsEnables experimental support for decorators, which is in stage 2\nof the TC39 standardization process.
\nDecorators are a language feature which hasn’t yet been fully ratified into the JavaScript specification.\nThis means that the implementation version in TypeScript may differ from the implementation in JavaScript when it it decided by TC39.
\nYou can find out more about decorator support in TypeScript in the handbook.
\n| Flag | experimentalDecorators \n | |
| Related | \n |
emitDecoratorMetadataEnables experimental support for emitting type metadata for decorators which works with the module reflect-metadata.
For example, here is the JavaScript
\n\ntsfunction LogMethod(function LogMethod(target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor): void\n target:(parameter) target: any any,\n propertyKey:(parameter) propertyKey: string | symbol string | symbol,\n descriptor:(parameter) descriptor: PropertyDescriptor PropertyDescriptorinterface PropertyDescriptor\n) {\n console.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): voidtarget)(parameter) target: any\n console.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): voidpropertyKey)(parameter) propertyKey: string | symbol\n console.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): voiddescriptor)(parameter) descriptor: PropertyDescriptor\n}\n\nclass Demo class Demo\n @LogMethodfunction LogMethod(target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor): void\n public foo((method) Demo.foo(bar: number): voidbar:(parameter) bar: number number) {\n // do nothing\n }\n}\n\nconst demo const demo: Demo= new Demo(constructor Demo(): Demo);
With emitDecoratorMetadata not set to true (default):
\njs\"use strict\";\nvar __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {\n var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;\n if (typeof Reflect === \"object\" && typeof Reflect.decorate === \"function\") r = Reflect.decorate(decorators, target, key, desc);\n else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;\n return c > 3 && r && Object.defineProperty(target, key, r), r;\n};\nfunction LogMethod(target, propertyKey, descriptor) {\n console.log(target);\n console.log(propertyKey);\n console.log(descriptor);\n}\nclass Demo {\n foo(bar) {\n // do nothing\n }\n}\n__decorate([\n LogMethod\n], Demo.prototype, \"foo\", null);\nconst demo = new Demo();
With emitDecoratorMetadata set to true:
\njs\"use strict\";\nvar __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {\n var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;\n if (typeof Reflect === \"object\" && typeof Reflect.decorate === \"function\") r = Reflect.decorate(decorators, target, key, desc);\n else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;\n return c > 3 && r && Object.defineProperty(target, key, r), r;\n};\nvar __metadata = (this && this.__metadata) || function (k, v) {\n if (typeof Reflect === \"object\" && typeof Reflect.metadata === \"function\") return Reflect.metadata(k, v);\n};\nfunction LogMethod(target, propertyKey, descriptor) {\n console.log(target);\n console.log(propertyKey);\n console.log(descriptor);\n}\nclass Demo {\n foo(bar) {\n // do nothing\n }\n}\n__decorate([\n LogMethod,\n __metadata(\"design:type\", Function),\n __metadata(\"design:paramtypes\", [Number]),\n __metadata(\"design:returntype\", void 0)\n], Demo.prototype, \"foo\", null);\nconst demo = new Demo();
| Flag | emitDecoratorMetadata \n | |
| Related | \n |
Flags which help with debugging
\nimportHelpersFor certain downleveling operations, TypeScript uses some helper code for operations like extending class, spreading arrays or objects, and async operations.\nBy default, these helpers are inserted into files which use them.\nThis can result in code duplication if the same helper is used in many different modules.
\nIf the importHelpers flag is on, these helper functions are instead imported from the tslib module.\nYou will need to ensure that the tslib module is able to be imported at runtime.\nThis only affects modules; global script files will not attempt to import modules.
For example, with this TypeScript:
\n\ntsexport function fn(arr: number[]) {\n const arr2 = [1, ...arr];\n}
Turning on downlevelIteration and importHelpers is still false:
\njsvar __read = (this && this.__read) || function (o, n) {\n var m = typeof Symbol === \"function\" && o[Symbol.iterator];\n if (!m) return o;\n var i = m.call(o), r, ar = [], e;\n try {\n while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);\n }\n catch (error) { e = { error: error }; }\n finally {\n try {\n if (r && !r.done && (m = i[\"return\"])) m.call(i);\n }\n finally { if (e) throw e.error; }\n }\n return ar;\n};\nvar __spread = (this && this.__spread) || function () {\n for (var ar = [], i = 0; i < arguments.length; i++) ar = ar.concat(__read(arguments[i]));\n return ar;\n};\nexport function fn(arr) {\n var arr2 = __spread([1], arr);\n}
Then turning on both downlevelIteration and importHelpers:
\njsimport { __read, __spread } from \"tslib\";\nexport function fn(arr) {\n var arr2 = __spread([1], arr);\n}
You can use noEmitHelpers when you provide your own implementations of these functions.
| Flag | importHelpers \n | |
| Default |
|
listFilesPrint names of files part of the compilation. This is useful when you are not sure that TypeScript has\nincluded a file you expected.
\nFor example:
\nexample\n├── index.ts\n├── package.json\n└── tsconfig.json\nWith:
\n\njson{\n \"compilerOptions\": {\n \"listFiles\": true\n }\n}
Would echo paths like:
\n$ npm run tsc\npath/to/example/node_modules/typescript/lib/lib.d.ts\npath/to/example/node_modules/typescript/lib/lib.es5.d.ts\npath/to/example/node_modules/typescript/lib/lib.dom.d.ts\npath/to/example/node_modules/typescript/lib/lib.webworker.importscripts.d.ts\npath/to/example/node_modules/typescript/lib/lib.scripthost.d.ts\npath/to/example/index.ts\n| Flag | listFiles \n | |
| Default |
|
listEmittedFilesPrint names of generated files part of the compilation to the terminal.
\nThis flag is useful in two cases:
\nFor example:
\nexample\n├── index.ts\n├── package.json\n└── tsconfig.json\nWith:
\n\njson{\n \"compilerOptions\": {\n \"declaration\": true,\n \"listFiles\": true\n }\n}
Would echo paths like:
\n$ npm run tsc\n\npath/to/example/index.js\npath/to/example/index.d.ts\nNormally, TypeScript would return silently on success.
\n| Flag | listEmittedFiles \n | |
| Default |
|
traceResolutionWhen you are trying to debug why a module isn’t being included.\nYou can set traceResolutions to true to have TypeScript print information about its resolution process for each processed file.
You can read more about this in the handbook.
\n| Flag | traceResolution \n | |
| Default |
| |
| Released | \n |
diagnosticsUsed to output diagnostic information for debugging. This command is a subset of extendedDiagnostics which are more user-facing results, and easier to interpret.
If you have been asked by a TypeScript compiler engineer to give the results using this flag in a compile, in which there is no harm in using --extendedDiagnostics instead.
| Flag | diagnostics \n | |
| Status | Deprecated \n | |
| Default |
| |
| Related | \n | |
| Status | Deprecated \n |
extendedDiagnosticsYou can use this flag to discover where TypeScript is spending it’s time when compiling.\nThis is a tool used for understanding the performance characteristics of your codebase overall.
\nYou can learn more about how to measure and understand the output in the performance section of the wiki.
\n| Flag | extendedDiagnostics \n | |
| Default |
| |
| Related | \n |
generateCpuProfileThis 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.
\nThis option can only be used from the CLI via: --generateCpuProfile tsc-output.cpuprofile.
\nshnpm 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.\nYou can learn more about understanding the compilers performance in the TypeScript wiki section on performance.
\n| Flag | generateCpuProfile \n | |
| Default | profile.cpuprofile \n | |
| Released | \n |
assumeChangesOnlyAffectDirectDependenciesWhen this option is enabled, TypeScript will avoid rechecking/rebuilding all truly possibly-affected files, and only recheck/rebuild files that have changed as well as files that directly import them.
\nThis can be considered a ‘fast & loose’ implementation of the watching algorithm, which can drastically reduce incremental rebuild times at the expense of having to run the full build occasionally to get all compiler error messages.
\n| Flag | assumeChangesOnlyAffectDirectDependencies \n | |
| Released | \n |
emitDeclarationOnlyOnly emit .d.ts files; do not emit .js files.
This setting is useful in two cases:
\nd.ts files for your consumers.| Flag | emitDeclarationOnly \n | |
| Default |
| |
| Released | \n |
importsNotUsedAsValuesThis flag controls how import works, there are 3 different options:
remove: The default behavior of dropping import statements which only reference types.preserve: Preserves all import statements whose values or types are never used. This can cause imports/side-effects to be preserved.error: This preserves all imports (the same as the preserve option), but will error when a value import is only used as a type. This might be useful if you want to ensure no values are being accidentally imported, but still make side-effect imports explicit.This flag works because you can use import type to explicitly create an import statement which should never be emitted into JavaScript.
| Flag | importsNotUsedAsValues \n | |
| Allowed | remove, preserve, error \n | |
| Released | \n |
jsxFactoryChanges the function called in .js files when compiling JSX Elements.\nThe 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.
| Flag | jsxFactory \n | |
| Default |
| |
| Allowed | Allowed Values: Any identifier or dotted identifier; default |
resolveJsonModuleAllows importing modules with a ‘.json’ extension, which is a common practice in node projects. This includes\ngenerating a type for the import based on the static JSON shape.
TypeScript does not support resolving JSON files by default:
\n\nts// @filename: settings.json\n{\n \"repo\": \"TypeScript\",\n \"dry\": false,\n \"debug\": false\n}\n// @filename: index.ts\nimport settings from \"./settings.json\";\n\nsettings.debug === true;\nsettings.dry === 2;
Enabling the option allows importing JSON, and validating the types in that JSON file.
\n\nts// @filename: settings.json\n{\n \"repo\": \"TypeScript\",\n \"dry\": false,\n \"debug\": false\n}\n// @filename: index.ts\nimport settings from \"./settings.json\";\n\nsettings.debug === true;\nsettings.dry === 2;
| Flag | resolveJsonModule \n | |
| Default |
|
outreactNamespaceUse --jsxFactory instead. Specify the object invoked for createElement when targeting react for TSX files.
| Flag | reactNamespace \n | |
| Default |
|
skipDefaultLibCheckUse --skipLibCheck instead. Skip type checking of default library declaration files.
| Flag | skipDefaultLibCheck \n | |
| Default |
|
charsetIn prior versions of TypeScript, this controlled what encoding was used when reading text files from disk.\nToday, TypeScript assumes UTF-8 encoding, but will correctly detect UTF-16 (BE and LE) or UTF-8 BOMs.
\n| Flag | charset \n | |
| Status | Deprecated \n | |
| Default |
| |
| Status | Deprecated \n |
emitBOMControls whether TypeScript will emit a byte order mark (BOM) when writing output files.\nSome runtime environments require a BOM to correctly interpret a JavaScript files; others require that it is not present.\nThe default value of false is generally best unless you have a reason to change it.
| Flag | emitBOM \n | |
| Default |
|
newLineSpecify the end of line sequence to be used when emitting files: ‘CRLF’ (dos) or ‘LF’ (unix).
\n| Flag | newLine \n | |
| Default | Platform specific \n | |
| Released | \n |
noErrorTruncationDo not truncate error messages.
\nWith false, the default.
\ntsvar x:var x: { propertyWithAnExceedinglyLongName1: string; propertyWithAnExceedinglyLongName2: string; propertyWithAnExceedinglyLongName3: string; propertyWithAnExceedinglyLongName4: string; propertyWithAnExceedinglyLongName5: string; } {\n propertyWithAnExceedinglyLongName1:(property) propertyWithAnExceedinglyLongName1: string string;\n propertyWithAnExceedinglyLongName2:(property) propertyWithAnExceedinglyLongName2: string string;\n propertyWithAnExceedinglyLongName3:(property) propertyWithAnExceedinglyLongName3: string string;\n propertyWithAnExceedinglyLongName4:(property) propertyWithAnExceedinglyLongName4: string string;\n propertyWithAnExceedinglyLongName5:(property) propertyWithAnExceedinglyLongName5: string string;\n};\n\n// String representation of type of 'x' should be truncated in error message\nvar s:var s: string string = x;var x: { propertyWithAnExceedinglyLongName1: string; propertyWithAnExceedinglyLongName2: string; propertyWithAnExceedinglyLongName3: string; propertyWithAnExceedinglyLongName4: string; propertyWithAnExceedinglyLongName5: string; }\nType '{ propertyWithAnExceedinglyLongName1: string; propertyWithAnExceedinglyLongName2: string; propertyWithAnExceedinglyLongName3: string; propertyWithAnExceedinglyLongName4: string; propertyWithAnExceedinglyLongName5: string; }' is not assignable to type 'string'.Variable 'x' is used before being assigned.2322
2454Type '{ propertyWithAnExceedinglyLongName1: string; propertyWithAnExceedinglyLongName2: string; propertyWithAnExceedinglyLongName3: string; propertyWithAnExceedinglyLongName4: string; propertyWithAnExceedinglyLongName5: string; }' is not assignable to type 'string'.Variable 'x' is used before being assigned.
With true
\ntsvar x:var x: { propertyWithAnExceedinglyLongName1: string; propertyWithAnExceedinglyLongName2: string; propertyWithAnExceedinglyLongName3: string; propertyWithAnExceedinglyLongName4: string; propertyWithAnExceedinglyLongName5: string; } {\n propertyWithAnExceedinglyLongName1:(property) propertyWithAnExceedinglyLongName1: string string;\n propertyWithAnExceedinglyLongName2:(property) propertyWithAnExceedinglyLongName2: string string;\n propertyWithAnExceedinglyLongName3:(property) propertyWithAnExceedinglyLongName3: string string;\n propertyWithAnExceedinglyLongName4:(property) propertyWithAnExceedinglyLongName4: string string;\n propertyWithAnExceedinglyLongName5:(property) propertyWithAnExceedinglyLongName5: string string;\n};\n\n// String representation of type of 'x' should be truncated in error message\nvar s:var s: string string = x;var x: { propertyWithAnExceedinglyLongName1: string; propertyWithAnExceedinglyLongName2: string; propertyWithAnExceedinglyLongName3: string; propertyWithAnExceedinglyLongName4: string; propertyWithAnExceedinglyLongName5: string; }\nType '{ propertyWithAnExceedinglyLongName1: string; propertyWithAnExceedinglyLongName2: string; propertyWithAnExceedinglyLongName3: string; propertyWithAnExceedinglyLongName4: string; propertyWithAnExceedinglyLongName5: string; }' is not assignable to type 'string'.Variable 'x' is used before being assigned.2322
2454Type '{ propertyWithAnExceedinglyLongName1: string; propertyWithAnExceedinglyLongName2: string; propertyWithAnExceedinglyLongName3: string; propertyWithAnExceedinglyLongName4: string; propertyWithAnExceedinglyLongName5: string; }' is not assignable to type 'string'.Variable 'x' is used before being assigned.
| Flag | noErrorTruncation \n | |
| Status | Deprecated \n | |
| Default |
| |
| Status | Deprecated \n |
noLibDisables the automatic inclusion of any library files.\nIf this option is set, lib is ignored.
| Flag | noLib \n | |
| Default |
| |
| Related | \n |
noResolveBy 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.\nHowever, 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.
| Flag | noResolve \n | |
| Default |
|
stripInternalDo not emit declarations for code that has an @internal annotation in it’s JSDoc comment.\nThis is an internal compiler option; use at your own risk, because the compiler does not check that the result is valid.\nIf you are searching for a tool to handle additional levels of visibility within your d.ts files, look at api-extractor.
\nts/**\n * Days available in a week\n * @internal\n */\nexport const daysInAWeek const daysInAWeek: 7= 7;\n\n/** Calculate how much someone earns in a week */\nexport function weeklySalary(function weeklySalary(dayRate: number): numberdayRate:(parameter) dayRate: number number) {\n return daysInAWeek const daysInAWeek: 7* dayRate;(parameter) dayRate: number\n}
With the flag set to false (default):
\nts/**\n * Days available in a week\n * @internal\n */\nexport declare const daysInAWeek = 7;\n/** Calculate how much someone earns in a week */\nexport declare function weeklySalary(dayRate: number): number;
With stripInternal set to true the d.ts emitted will be redacted.
\nts/** Calculate how much someone earns in a week */\nexport declare function weeklySalary(dayRate: number): number;
The JavaScript output is still the same.
\n| Flag | stripInternal \n | |
| Status | internal \n |
disableSizeLimitTo avoid a possible memory bloat issue when working with very large JavaScript projects, there is an upper limit to the amount of memory TypeScript will allocate. Turning this flag on will remove the limit.
\n| Flag | disableSizeLimit \n | |
| Default |
|
disableSourceOfProjectReferenceRedirectWhen 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.\nIn 3.7 the source of truth is now your TypeScript files.
\n| Flag | disableSourceOfProjectReferenceRedirect \n | |
| Released | \n |
disableSolutionSearchingWhen working with composite TypeScript projects, this option provides a way to declare that you do not want a project to be included when using features like find all references or jump to definition in an editor.
\nThis flag is something you can use to increase responsiveness in large composite projects.
\n| Flag | disableSolutionSearching \n | |
| Released | \n |
noImplicitUseStrictYou 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.\nThis setting disables the prologue.
\njsdefine([\"require\", \"exports\"], function (require, exports) {\n exports.__esModule = true;\n function fn() { }\n exports.fn = fn;\n});
\njsdefine([\"require\", \"exports\"], function (require, exports) {\n \"use strict\";\n exports.__esModule = true;\n function fn() { }\n exports.fn = fn;\n});
| Flag | noImplicitUseStrict \n | |
| Default |
|
noEmitHelpersInstead 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:
\ntsconst getAPI const getAPI: (url: string) => Promise<{}>= async (url:(parameter) url: string string) => {\n // Get API\n return {};\n};
Which creates quite a lot of JavaScript:
\n\njs\"use strict\";\nvar __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {\n function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }\n return new (P || (P = Promise))(function (resolve, reject) {\n function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }\n function rejected(value) { try { step(generator[\"throw\"](value)); } catch (e) { reject(e); } }\n function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }\n step((generator = generator.apply(thisArg, _arguments || [])).next());\n });\n};\nvar __generator = (this && this.__generator) || function (thisArg, body) {\n var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;\n return g = { next: verb(0), \"throw\": verb(1), \"return\": verb(2) }, typeof Symbol === \"function\" && (g[Symbol.iterator] = function() { return this; }), g;\n function verb(n) { return function (v) { return step([n, v]); }; }\n function step(op) {\n if (f) throw new TypeError(\"Generator is already executing.\");\n while (_) try {\n 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;\n if (y = 0, t) op = [op[0] & 2, t.value];\n switch (op[0]) {\n case 0: case 1: t = op; break;\n case 4: _.label++; return { value: op[1], done: false };\n case 5: _.label++; y = op[1]; op = [0]; continue;\n case 7: op = _.ops.pop(); _.trys.pop(); continue;\n default:\n if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }\n if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }\n if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }\n if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }\n if (t[2]) _.ops.pop();\n _.trys.pop(); continue;\n }\n op = body.call(thisArg, _);\n } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }\n if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };\n }\n};\nvar getAPI = function (url) { return __awaiter(void 0, void 0, void 0, function () {\n return __generator(this, function (_a) {\n // Get API\n return [2 /*return*/, {}];\n });\n}); };
Which can be switched out with your own globals via this flag:
\n\njs\"use strict\";\nvar getAPI = function (url) { return __awaiter(void 0, void 0, void 0, function () {\n return __generator(this, function (_a) {\n // Get API\n return [2 /*return*/, {}];\n });\n}); };
| Flag | noEmitHelpers \n | |
| Default |
| |
| Related | \n | |
| Released | \n |
noEmitOnErrorDo not emit compiler output files like JavaScript source code, source-maps or declarations if any errors were reported.
\nThis 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.
| Flag | noEmitOnError \n | |
| Default |
| |
| Released | \n |
preserveConstEnumsDo not erase const enum declarations in generated code. const enums provide a way to reduce the overall memory footprint\nof your application at runtime by emitting the enum value instead of a reference.
For example with this TypeScript:
\n\ntsconst enum Album const enum Album\n JimmyEatWorldFutures (enum member) Album.JimmyEatWorldFutures = 1= 1,\n TubRingZooHypothesis (enum member) Album.TubRingZooHypothesis = 2= 2,\n DogFashionDiscoAdultery (enum member) Album.DogFashionDiscoAdultery = 3= 3\n}\n\nconst selectedAlbum const selectedAlbum: Album.JimmyEatWorldFutures= Album.const enum AlbumJimmyEatWorldFutures;(enum member) Album.JimmyEatWorldFutures = 1\nif (selectedAlbum const selectedAlbum: Album.JimmyEatWorldFutures=== Album.const enum AlbumJimmyEatWorldFutures)(enum member) Album.JimmyEatWorldFutures = 1 {\n console.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): void\"That is a great choice.\");\n}
The default const enum behavior is to convert any Album.Something to the corresponding number literal, and to remove a reference\nto the enum from the JavaScript completely.
\njs\"use strict\";\nconst selectedAlbum = 1 /* JimmyEatWorldFutures */;\nif (selectedAlbum === 1 /* JimmyEatWorldFutures */) {\n console.log(\"That is a great choice.\");\n}
With preserveConstEnums set to true, the enum exists at runtime and the numbers are still emitted.
\njs\"use strict\";\nvar Album;\n(function (Album) {\n Album[Album[\"JimmyEatWorldFutures\"] = 1] = \"JimmyEatWorldFutures\";\n Album[Album[\"TubRingZooHypothesis\"] = 2] = \"TubRingZooHypothesis\";\n Album[Album[\"DogFashionDiscoAdultery\"] = 3] = \"DogFashionDiscoAdultery\";\n})(Album || (Album = {}));\nconst selectedAlbum = 1 /* JimmyEatWorldFutures */;\nif (selectedAlbum === 1 /* JimmyEatWorldFutures */) {\n console.log(\"That is a great choice.\");\n}
This essentially makes such const enums a source-code feature only, with no runtime traces.
| Flag | preserveConstEnums \n | |
| Default |
|
declarationDirOffers a way to configure the root directory for where declaration files are emitted.
\nexample\n├── index.ts\n├── package.json\n└── tsconfig.json\nwith this tsconfig.json:
\njson{\n \"compilerOptions\": {\n \"declaration\": true,\n \"declarationDir\": \"./types\"\n }\n}
Would place the d.ts for the index.ts in a types folder:
example\n├── index.js\n├── index.ts\n├── package.json\n├── tsconfig.json\n└── types\n └── index.d.ts\n| Flag | declarationDir \n | |
| Default | n/a \n | |
| Released | \n |
skipLibCheckSkip type checking of declaration files.
\nThis can save time during compilation at the expense of type-system accuracy. For example, two libraries could\ndefine two copies of the same type in an inconsistent way. Rather than doing a full check of all d.ts files, TypeScript\nwill type check the code you specifically refer to in your app’s source code.
A common case where you might think to use skipLibCheck is when there are two copies of a library’s types in\nyour node_modules. In these cases, you should consider using a feature like yarn’s resolutions\nto ensure there is only one copy of that dependency in your tree or investigate how to ensure there is\nonly one copy by understanding the dependency resolution to fix the issue without additional tooling.
| Flag | skipLibCheck \n | |
| Default |
| |
| Released | \n |
allowUnusedLabelsSet to false to disable warnings about unused labels.
\nLabels are very rare in JavaScript and typically indicate an attempt to write an object literal:
\n\ntsfunction verifyAge(function verifyAge(age: number): voidage:(parameter) age: number number) {\n // Forgot 'return' statement\n if (age (parameter) age: number> 18) {\n verified:true;\nUnused label.7028Unused label. }\n}
| Flag | allowUnusedLabels \n | |
| Default |
| |
| Released | \n |
allowUnreachableCodeSet to false to disable warnings about unreachable code.\nThese warnings are only about code which is provably unreachable due to the use of JavaScript syntax, for example:
\n\ntsfunction fn(n: number) {\n if (n > 5) {\n return true;\n } else {\n return false;\n }\n return true;\n}
With \"allowUnreachableCode\": false:
\ntsfunction fn(function fn(n: number): booleann:(parameter) n: number number) {\n if (n (parameter) n: number> 5) {\n return true;\n } else {\n return false;\n }\n return true;\nUnreachable code detected.7027Unreachable code detected.}
This does not affect errors on the basis of code which appears to be unreachable due to type analysis.
\n| Flag | allowUnreachableCode \n | |
| Default |
| |
| Released | \n |
suppressExcessPropertyErrorsThis disables reporting of excess property errors, such as the one shown in the following example:
\n\ntstype Point type Point = { x: number; y: number; }= { x:(property) x: number number; y:(property) y: number number };\nconst p:const p: Point Point type Point = { x: number; y: number; }= { x:(property) x: number1, y:(property) y: number3, m:(property) m: number10 };\nType '{ x: number; y: number; m: number; }' is not assignable to type 'Point'.\n Object literal may only specify known properties, and 'm' does not exist in type 'Point'.2322Type '{ x: number; y: number; m: number; }' is not assignable to type 'Point'.\n Object literal may only specify known properties, and 'm' does not exist in type 'Point'.
This flag was added to help people migrate to the stricter checking of new object literals in TypeScript 1.6.
\nWe don’t recommend using this flag in a modern codebase, you can suppress one-off cases where you need it using // @ts-ignore.
| Flag | suppressExcessPropertyErrors \n | |
| Default |
|
suppressImplicitAnyIndexErrorsTurning noImplicitAny on suppresses reporting the error about implicit anys when indexing into objects, as shown in the following example:
\ntsconst obj const obj: { x: number; }= { x:(property) x: number10 };\nconsole.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): voidobj[const obj: { x: number; }\"foo\"]);\nElement implicitly has an 'any' type because expression of type '\"foo\"' can't be used to index type '{ x: number; }'.\n Property 'foo' does not exist on type '{ x: number; }'.7053Element implicitly has an 'any' type because expression of type '\"foo\"' can't be used to index type '{ x: number; }'.\n Property 'foo' does not exist on type '{ x: number; }'.
Using suppressImplicitAnyIndexErrors is quite a drastic approach. It is recommended to use a @ts-ignore comment instead:
\ntsconst obj const obj: { x: number; }= { x:(property) x: number10 };\n// @ts-ignore\nconsole.var console: Consolelog((method) Console.log(message?: any, ...optionalParams: any[]): voidobj[const obj: { x: number; }\"foo\"]);
| Flag | suppressImplicitAnyIndexErrors \n | |
| Default |
|
forceConsistentCasingInFileNamesTypeScript follows the case sensitivity rules of the file system it’s running on.\nThis can be problematic if some developers are working in a case-sensitive file system and others aren’t.\nIf 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.
\n| Flag | forceConsistentCasingInFileNames \n | |
| Recommended | True \n | |
| Default |
|
maxNodeModuleJsDepthThe maximum dependency depth to search under node_modules and load JavaScript files.
This flag is can only be used when allowJs is enabled, and is used if you want to have TypeScript infer types for all of the JavaScript inside your node_modules.
Ideally this should stay at 0 (the default), and d.ts files should be used to explicitly define the shape of modules.\nHowever, there are cases where you may want to turn this on at the expense of speed and potential accuracy.
| Flag | maxNodeModuleJsDepth \n | |
| Default |
|
noStrictGenericChecksTypeScript will unify type parameters when comparing two generic functions functions
\n\ntstype A type A = <T, U>(x: T, y: U) => [T, U]= <T,(type parameter) T in <T, U>(x: T, y: U): [T, U] U>(type parameter) U in <T, U>(x: T, y: U): [T, U](x:(parameter) x: T T,(type parameter) T in <T, U>(x: T, y: U): [T, U] y:(parameter) y: U U)(type parameter) U in <T, U>(x: T, y: U): [T, U]=> [T,(type parameter) T in <T, U>(x: T, y: U): [T, U] U](type parameter) U in <T, U>(x: T, y: U): [T, U]\ntype B type B = <S>(x: S, y: S) => [S, S]= <S>(type parameter) S in <S>(x: S, y: S): [S, S](x:(parameter) x: S S,(type parameter) S in <S>(x: S, y: S): [S, S] y:(parameter) y: S S)(type parameter) S in <S>(x: S, y: S): [S, S]=> [S,(type parameter) S in <S>(x: S, y: S): [S, S] S](type parameter) S in <S>(x: S, y: S): [S, S]\n\nfunction f(function f(a: A, b: B): voida:(parameter) a: A A,type A = <T, U>(x: T, y: U) => [T, U] b:(parameter) b: B B)type B = <S>(x: S, y: S) => [S, S] {\n b (parameter) b: B= a;(parameter) a: A// Ok\n a (parameter) a: A= b;(parameter) b: B// Error\nType 'B' is not assignable to type 'A'.\n Types of parameters 'y' and 'y' are incompatible.\n Type 'U' is not assignable to type 'T'.\n 'U' is assignable to the constraint of type 'T', but 'T' could be instantiated with a different subtype of constraint '{}'.2322Type 'B' is not assignable to type 'A'.\n Types of parameters 'y' and 'y' are incompatible.\n Type 'U' is not assignable to type 'T'.\n 'U' is assignable to the constraint of type 'T', but 'T' could be instantiated with a different subtype of constraint '{}'.}
This flag can be used to remove that check.
\n| Flag | noStrictGenericChecks \n | |
| Default |
| |
| Released | \n |
useDefineForClassFieldsThis flag is used as part of migrating to the upcoming standard version of class fields. TypeScript introduced class fields many years before it was ratified in TC39. The latest version of the upcoming specification has a different runtime behavior to TypeScript’s implementation but the same syntax.
\nThis flag switches to the upcoming ECMA runtime behavior.
\nYou can read more about the transition in the 3.7 release notes.
\n| Flag | useDefineForClassFields \n | |
| Released | \n |
keyofStringsOnlyThis flag changes the keyof type operator to return string instead of string | number when applied to a type with a string index signature.
This flag is used to help people keep this behavior from before TypeScript 2.9’s release.
\n| Flag | keyofStringsOnly \n | |
| Status | Deprecated \n | |
| Default |
| |
| Status | Deprecated \n | |
| Released | \n |
preserveWatchOutputWhether to keep outdated console output in watch mode instead of clearing the screen every time a change happened.
\n| Flag | preserveWatchOutput \n | |
| Default |
| |
| Status | internal \n |
prettyStylize errors and messages using color and context, this is on by default — offers you a chance to have less terse,\nsingle colored messages from the compiler.
\n| Flag | pretty \n | |
| Default |
|