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.
Sources
tsc CLI OptionsHelp 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 likeObject
,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. Thoughclassic
is the default setting for some--module
selections, it will be deprecated in TypeScript 6. Node projects should usenode16
ornodenext
, 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.
Sources
Supporting lib from node_modules The module output format The module compiler option Modules - Choosing Compiler OptionsSource 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 thets
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 ises6
(also specified withes2015
), orCommonJS
if--target
ises5
.es2020
produces ES6 modules, while adding support for dynamic imports andimport.meta
metadata.es2022
adds top-levelawait
.esnext
andnodenext
target current versions of JavaScript and Node, and will incorporate new features as those are standardized.Node projects should use
node16
ornodenext
, notcommonjs
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 thepackage.json
in its folder or an ancestor folder to identify its module type.cts
andmts
files are considered to be CommonJS or ECMAScript modules, respectively.ts
files are considered to be ECMAScript modules if thetype
property in itspackage.json
is set tomodule
. 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 thejs
output, except those explicitly defined as type-only withimport type
.
Source output options
-
--target value
-
Specifies the JavaScript version to be used when generating
js
files. The default ises5
.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 thets
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 toNone
,System
, orAMD
. -
--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
orcrlf
. The default islf
. -
--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
andjsx.map
source map files that associatejs
files with thets
files that generated them. The flag adds comments to the compiledjs
files; those comments reference the map files, which then reference thets
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
-
Enables strict mode for all files, and adds
"use strict"
to alljs
output. -
--strictNullChecks
-
Associates unique types with
undefined
andnull
, which are added to the union of types that qualify a variable or other element, ifundefined
ornull
are possible values. This produces a build error if the element is read without checking forundefined
ornull
. -
--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
, orapply
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 thanany
. -
--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 ofthis
is not known. -
--noFallthroughCasesInSwitch
-
Produces a build error if any
case
statement lacks abreak
,return
, orthrow
. -
--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 totrue
suppresses those warnings instead. Setting it tofalse
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 asany
orunknown
. By default, if it is not explicitly typed, it is considered to beany
. This option causes it to be consideredunknown
instead.
Sources
Strict Builtin Iterator ChecksBuild 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 infiles
orinclude
withintsconfig.json
.When specified on the command line, this option can only be disabled, by passing
false
ornull
as an argument. It can be enabled only withintsconfig.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
.
Sources
Project Referencestsconfig.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.
Sources
TSConfig ReferenceGeneral sources
The TypeScript Handbook
Microsoft