TypeScript Notes

Compiled by Jeremy Kelly
www.anthemion.org

Printed UNKNOWN

These are my TypeScript notes, covering version 5. They are not complete, but I am working on them now. If you find a mistake, please let me know.

The example code uses a new notation I am developing. More on that soon.

This page includes a two-column print style. For best results, print in landscape, apply narrow margins, change the Scale setting in your browser’s print options to 70%, and enable background graphics. Firefox and Chrome each have their own set of printing bugs, but one of them usually works.

Contents

• tsc
• Help and setup options
• General build options
• Library and module input options
• Source input options
• Declaration output options
• Module output options
• Source output options
• Source map output options
• Error checking options
• Build mode options
• tsconfig.json
• General sources

tsc

The typescript package includes a transpiler tsc, which translates TypeScript into JavaScript. Tools like Babel can also transpile it.

tsc supports numerous command line options, but these are typically added to tsconfig.json files, rather than being passed on the command line. TypeScript filenames or globs can also be passed as tsc arguments. tsconfig.json is ignored when source files are specified this way.

Help and setup options

-h

--help

Lists commonly-used compiler options.

--all

Lists all compiler options.

--init

Creates a tsconfig.json file in the current folder.

General build options

-p path

--project path

Builds using the specified configuration file, or with the tsconfig.json file in the specified folder.

--showConfig

Displays the content of the tsconfig.json that would be used during a build, without actually building.

--noEmitOnError

Prevents output file generation if build errors are reported.

--diagnostics

--extendedDiagnostics

Displays compilation performance data, including total build time.

Library and module input options

--lib versionList

tsc provides declaration files that describe standard JavaScript functions and containers, plus the DOM API. By default, it uses the --target setting to decide which version of these libraries to include. This option can be used to select a different version, or to include some libraries while excluding others. Library versions can also be selected by configuring the package manager.

--noLib

Stops tsc from automatically including library declaration files, even if --lib is set. The developer must provide their own declarations for types like Object, Function, String, et cetera.

--moduleDetection

Determines how tsc decides whether a source file is a module.

--moduleResolution

Determines how tsc finds the files referenced by module imports, so that their types can be identified. This is called module resolution. Though classic is the default setting for some --module selections, it will be deprecated in TypeScript 6. Node projects should use node16 or nodenext, which are the defaults for the corresponding --module selections. Other configurations are more complex; these are addressed the TypeScript documentation.

--rootDirs pathList

Defines one or more folders that are implicitly merged (along with their subfolders) with the source folder hierarchy when resolving import paths. The modules in the various hierarchies can then be specified as if they were part of a single directory structure. This should not be confused with --rootDir, which affects the folder hierarchy created within the --outDir folder.

--traceResolution

Displays build output that explains why each module was included and how it was resolved.

--allowArbitraryExtensions

The module name inside an import is called a module specifier. This flag disables the build error that normally occurs when a specifier includes an unexpected file extension.

--moduleSuffixes suffixList

Provides a list of suffixes to be appended automatically to module specifiers when resolving these to files.

--resolveJsonModule

Allows JSON files to be imported as JavaScript objects:

import Data from "./data.json";

--noUncheckedSideEffectImports

Side effect imports are imports that bring nothing into scope. By default, tsc ignores these if the specified module is not found. This flag produces a build error instead.

--isolatedDeclarations

By default, TypeScript allows variable types and function signatures to be inferred from their definitions. Those definitions can themselves rely on inferred types (possibly from other modules) which causes declaration generation to take longer than it might. When this flag is set, exported variables and functions produce compile errors if their declarations would require non-trivial type inference.

Source input options

--allowJs

Allows plain JavaScript files to be used within the project. When disabled, importing a JavaScript file produces a compiler error.

--checkJs

Enables error checking for plain JavaScript files processed with --allowJs.

--listFiles

--explainFiles

--listFilesOnly

Lists all files that were read during the build, including external files referenced by internal project files. --explainFiles also gives the reason for each file's inclusion. --listFilesOnly lists them without actually building.

Declaration output options

--declaration

Produces type definition files in addition to normal build output. These files use the d.ts file extension. Like C/C++ headers, they describe the public interfaces of compiled modules.

--emitDeclarationOnly

Causes d.ts files to be generated without other build output.

--declarationDir path

Specifies a separate output folder for d.ts files.

--declarationMap

Produces source maps that link d.ts files to the ts files that generated them.

--stripInternal

Causes any export that includes an @internal directive in its JSDOC comment to be excluded from the declaration output.

Module output options

--module value

Determines the module type to be used in js file output. The default is es6 (also specified with es2015), or CommonJS if --target is es5. es2020 produces ES6 modules, while adding support for dynamic imports and import.meta metadata. es2022 adds top-level await. esnext and nodenext target current versions of JavaScript and Node, and will incorporate new features as those are standardized.

Node projects should use node16 or nodenext, not commonjs or any of the ECMAScript options. Node now supports both CommonJS and ECMAScript modules, so, like Node, tsc uses a source file's extension or the package.json in its folder or an ancestor folder to identify its module type. cts and mts files are considered to be CommonJS or ECMAScript modules, respectively. ts files are considered to be ECMAScript modules if the type property in its package.json is set to module. This decision affects the file's transpilation, plus its output file extension.

--verbatimModuleSyntax

TypeScript allows types and interfaces to be imported from modules; imports that only target these elements are called type-only imports. Because types have no use in JavaScript, these imports may be omitted from js file output, which prevents side effects from being performed. This flag ensures that all modules are imported in the js output, except those explicitly defined as type-only with import type.

Source output options

--target value

Specifies the JavaScript version to be used when generating js files. The default is es5. esnext uses the highest version supported by this version of TypeScript.

--outDir path

Determines the folder into which output files and folders will be placed. This includes compiled js files, declarations, source maps, and others. The source folder hierarchy will be reproduced as well. When this option not used, output files are placed in the source folders alongside the ts files that generated them.

--rootDir path

When combined with --outDir, this option specifies the root folder relative to which source file paths are compared when reproducing the source folder hierarchy inside the --outDir folder. This should not be confused with --rootDirs, which defines extra paths for module resolution.

--outFile pathName

Causes all non-module files to be concatenated into the specified output file. --module must be set to None, System, or AMD.

--listEmittedFiles

Lists all output files that were generated by the compiler.

--emitBOM

Adds UTF-8 byte-order marks to all output files.

--newLine

Determines whether output files end lines with lf or crlf. The default is lf.

--removeComments

Comments in source files are normally included in js file output. This flag removes them.

--jsx value

--jsxFactory value

--jsxFragmentFactory value

--jsxImportSource value

These settings determine whether and how JSX is transpiled in the js file output. They can be changed in specific files by adding @jsxRuntime, @jsx, @jsxFrag, @jsxImportSource directives to comments inside them.

Source map output options

--sourceMap

Produces js.map and jsx.map source map files that associate js files with the ts files that generated them. The flag adds comments to the compiled js files; those comments reference the map files, which then reference the ts files. This allows debuggers to show the original TypeScript while running the compiled JavaScript.

--inlineSourceMap

Produces source map data, but instead of storing it in source map files, this flag adds it to the js file comments that would reference those files, if --sourceMap were used instead.

--inlineSources

Adds ts file content directly to the source map files, if --sourceMap is used, or to the source map comments, if --inlineSourceMap is used.

Error checking options

--strict

Collectively enables these flags, which can be individually disabled after:

• alwaysStrict
• strictNullChecks
• strictBindCallApply
• strictFunctionTypes
• strictPropertyInitialization
• noImplicitAny
• noImplicitThis
• useUnknownInCatchVariable

--alwaysStrict

Enables strict mode for all files, and adds "use strict" to all js output.

--strictNullChecks

Associates unique types with undefined and null, which are added to the union of types that qualify a variable or other element, if undefined or null are possible values. This produces a build error if the element is read without checking for undefined or null.

--strictPropertyInitialization

Produces a build error if a class field is defined without being initialized in the body or assigned in the constructor. This does not apply if undefined is part of the field's type.

--strictFunctionTypes

Produces a build error if any non-method function is assigned to a type with less stringent parameter types.

--strictBindCallApply

Produces a build error if call, bind, or apply is invoked with arguments that fail to match the parent function.

--strictBuiltinIteratorReturn

Causes iterators to produce values that are qualified with a concrete type plus undefined, rather than any.

--noImplicitAny

TypeScript sometimes assumes a type of any if a type has not been specified, and cannot be inferred. This flag produces a build error instead.

--noImplicitOverride

Produces a build error if a subclass overrides a parent method without the override keyword.

--noImplicitReturns

Produces a build error if any function execution path lacks an explicit return, unless the function's return type is undefined.

--noImplicitThis

Produces a build error if properties are read from this in a context in which the type of this is not known.

--noFallthroughCasesInSwitch

Produces a build error if any case statement lacks a break, return, or throw.

--noUnusedLocals

--noUnusedParameters

Produces a build error if any local variable or function parameter is defined but not used.

--allowUnreachableCode

--allowUnusedLabels

By default, tsc produces warnings when it finds unreachable code or unused labels. Setting this option to true suppresses those warnings instead. Setting it to false produces build errors.

--exactOptionalPropertyTypes

Properties in types and interfaces can be suffixed with question marks to show that their presence is optional. Originally, these types and interfaces were satisfied when the optional properties were missing from the object, or when they were explicitly set to undefined. When this flag is set, undefined properties no longer satisfy these constraints.

--downlevelIteration

Causes code points containing multiple code units to be handled correctly when ECMAScript 6 iteration functionality is transpiled to older versions.

--useUnknownInCatchVariables

The exception parameter in a catch statement can be explicitly typed as any or unknown. By default, if it is not explicitly typed, it is considered to be any. This option causes it to be considered unknown instead.

Build mode options

Incremental builds can be performed by dividing a large project into smaller subsidiary projects. Each subsidiary has its own tsconfig.json file, which must include --composite. A single parent project references the others with project references, defined in the references property within its tsconfig.json. The parent can then be built with --build or -b, which enable build mode. This mode builds the subsidiary projects if they are out of date, then loads their declaration files, and then builds the parent.

Build mode options include:

-b [pathList]

--build [pathList]

Builds the projects referenced by pathList, with each element being the path to a tsconfig.json file or to a folder that contains one. If no pathList is provided, the current folder is assumed.

Before each pathList project is built, its project references are checked, and those projects are built, if they are out of date. This flag implicitly sets --noEmitOnError for all projects.

--composite

Allows this project to be included as a project reference when another project uses build mode. In particular, this flag enforces requirements that allow tsc to determine whether this project is up to date, or whether it needs to be rebuilt. It also implicitly enables --declaration. All source files in this project must be listed in files or include within tsconfig.json.

When specified on the command line, this option can only be disabled, by passing false or null as an argument. It can be enabled only within tsconfig.json.

--force

Builds all files in the project, even those that have not changed. This may be necessary when d.ts files or other build output is committed to source control, if the source control app does not preserve timestamps. Must be combined with --build.

--verbose

Builds the project with verbose log output. Must be combined with --build.

--clean

Cleans the project. Must be combined with --build.

tsconfig.json

When source files are not passed as command line arguments, tsc searches upward from the current folder for a tsconfig.json file. If no file is found, tsc displays the help, or produces an error, if --build was specified.

General sources

The TypeScript Handbook
Microsoft