tsconfig.json compiler options - Emit

Question 1

What does declaration compiler option do?

Answer 1

Generate .d.ts files for every TypeScript or JavaScript file inside your project. These .d.ts files are type definition files which describe the external API of your module.

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

Source typescriptlang

Question 2

What does declarationDir compiler option do?

Answer 2

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

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

Source typescriptlang

Question 3

What does declarationMap compiler option do?

Answer 3

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

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

{
	"compilerOptions": {
	  "declarationMap": true
	}
}

Source typescriptlang

Question 4

What does downlevelIteration compiler option do?

Answer 4

Downleveling is TypeScript’s term for transpiling to an older version of JavaScript. This flag is to enable support for a more accurate implementation of how modern JavaScript iterates through new concepts in older JavaScript runtimes.

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.

{
  "compilerOptions": {
    "downlevelIteration": "true"
  }
}

Source typescriptlang

Question 5

What does emitBOM compiler option do?

Answer 5

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.

{
  "compilerOptions": {
    "emitBOM": "true"
  }
}

Source typescriptlang

Question 6

What does emitDeclarationOnly compiler option do?

Answer 6

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

This setting is useful in two cases:

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

{
	"compilerOptions": {
	  "emitDeclarationOnly": true
	}
}

Source typescriptlang

Question 7

What does importHelpers compiler option do?

Answer 7

For certain downleveling operations, TypeScript uses some helper code for operations like extending class, spreading arrays or 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.

{
  "compilerOptions": {
    "importHelpers": "true"
  }
}

Source typescriptlang

Question 8

What does importsNotUsedAsValues compiler option do?

Answer 8

This 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.

Source typescriptlang

Question 9

What does inlineSourceMap compiler option do?

Answer 9

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.

Source typescriptlang

Question 10

What does inlineSources compiler option do?

Answer 10

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

Requires either sourceMap or inlineSourceMap to be set.

Source typescriptlang

Question 11

What does mapRoot compiler option do?

Answer 11

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

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

Source typescriptlang

Question 12

What does noEmit compiler option do?

Answer 12

Do not emit compiler output files like JavaScript source code, source-maps or declarations.

This 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.

You can then use TypeScript as a tool for providing editor integration, and as a source code type-checker.

Source typescriptlang

Question 13

What does noEmitHelpers compiler option do?

Answer 13

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.

Source typescriptlang

Question 14

What does noEmitOnError compiler option do?

Answer 14

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

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

Source typescriptlang

Question 15

What does outDir compiler option do?

Answer 15

If specified, .js (as well as .d.ts, .js.map, etc.) files will be emitted into this 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.

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

Source typescriptlang

Question 16

What does declaration compiler option do?

Answer 16

Generates .d.ts files for every TypeScript or JavaScript file inside your project.

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

Source typescriptlang

Question 17

What does outFile compiler option do?

Answer 17

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.

Source typescriptlang

Question 18

What does preserveConstEnums compiler option do?

Answer 18

Do not erase const enum declarations in generated code. const enums provide a way to reduce the overall memory footprint of your application at runtime by emitting the enum value instead of a reference.

Source typescriptlang

Question 19

What does preserveValueImports compiler option do?

Answer 19

There are some cases where TypeScript can’t detect that you’re using an import. For example, take the following code:

import { Animal } from "./animal.js";
eval("console.log(new Animal().isDangerous())");

When combined with isolatedModules, imported types must be marked as type-only because compilers that process single files at a time have no way of knowing whether imports are values that appear unused, or a type that must be removed in order to avoid a runtime crash.

For example, in the following code where TitleComponent is a function and TitleComponentProps is a type:

import { TitleComponent, TitleComponentProps } from "./TitleComponent.js";

This can be can be fixed by prefixing TitleComponentProps with type to mark it as a type-only import:

import { TitleComponent, type TitleComponentProps } from "./TitleComponent.js";

Source typescriptlang

Question 20

What does removeComments compiler option do?

Answer 20

Strips all comments from TypeScript files when converting into JavaScript. Defaults to false.

Source typescriptlang

Question 21

What does sourceMap compiler option do?

Answer 21

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.

{
  "compilerOptions": {
    "sourceMap": "true"
  }
}

Source typescriptlang

Question 22

What does sourceRoot compiler option do?

Answer 22

Specify the location where a debugger should locate TypeScript files instead of relative source locations. This string is treated verbatim inside the source-map where you can use a path or a URL:

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

Would declare that index.js will have a source file at https://my-website.com/debug/source/index.ts.

Source typescriptlang

Question 23

What does stripInternal compiler option do?

Answer 23

Do not emit declarations for code that has an @internal annotation in its JSDoc comment. This is an internal compiler option; use at your own risk, because the compiler does not check that the result is valid. If you are searching for a tool to handle additional levels of visibility within your d.ts files, look at api-extractor.