tsc - TypeScript Compiler

The tsc command is the TypeScript compiler that compiles TypeScript files to JavaScript.

Installation

npm install -g typescript

Basic Usage

tsc file.ts

Command-Line Options

Project Configuration

--project

string

default:"tsconfig.json"

Compile the project given the path to its configuration file, or to a folder with a tsconfig.json.Aliases: -p

tsc --project tsconfig.build.json
tsc -p src/

--init

boolean

default:"false"

Initializes a TypeScript project and creates a tsconfig.json file.

tsc --init

--showConfig

boolean

default:"false"

Print the final configuration instead of building.

tsc --showConfig

Build Options

--build

boolean

default:"false"

Build one or more projects and their dependencies, if out of date.Aliases: -b

tsc --build
tsc -b src/ test/

--watch

boolean

default:"false"

Watch input files and trigger recompilation on changes.Aliases: -w

tsc --watch
tsc -w

--incremental

boolean

default:"false"

Save .tsbuildinfo files to allow for incremental compilation of projects.Aliases: -i

tsc --incremental

Target & Module Options

--target

string

default:"ES3"

Set the JavaScript language version for emitted JavaScript and include compatible library declarations.Aliases: -tValid values: ES3, ES5, ES6/ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ES2023, ES2024, ES2025, ESNext

tsc --target ES2020
tsc -t ESNext

--module

string

default:"computed"

Specify what module code is generated.Aliases: -mValid values: CommonJS, AMD, UMD, System, ES6/ES2015, ES2020, ES2022, ESNext, Node16, Node18, Node20, NodeNext, Preserve

tsc --module commonjs
tsc -m ESNext

--lib

string[]

Specify a set of bundled library declaration files that describe the target runtime environment.Valid values: ES5, ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ES2023, ES2024, ES2025, ESNext, DOM, WebWorker, ScriptHost

tsc --lib ES2020,DOM

Emit Options

--outFile

string

Specify a file that bundles all outputs into one JavaScript file. If declaration is true, also designates a file that bundles all .d.ts output.

tsc --outFile bundle.js

--outDir

string

Specify an output folder for all emitted files.

tsc --outDir dist/

--declaration

boolean

default:"false"

Generate .d.ts files from TypeScript and JavaScript files in your project.Aliases: -d

tsc --declaration
tsc -d

--declarationMap

boolean

default:"false"

Create sourcemaps for d.ts files.

tsc --declaration --declarationMap

--sourceMap

boolean

default:"false"

Create source map files for emitted JavaScript files.

tsc --sourceMap

--removeComments

boolean

default:"false"

Disable emitting comments.

tsc --removeComments

--noEmit

boolean

default:"false"

Disable emitting files from a compilation.

tsc --noEmit

--emitDeclarationOnly

boolean

default:"false"

Only output d.ts files and not JavaScript files.

tsc --emitDeclarationOnly

Type Checking Options

--strict

boolean

default:"true"

Enable all strict type-checking options.

tsc --strict

--noImplicitAny

boolean

default:"true if strict"

Enable error reporting for expressions and declarations with an implied ‘any’ type.

tsc --noImplicitAny

--strictNullChecks

boolean

default:"true if strict"

When type checking, take into account null and undefined.

tsc --strictNullChecks

--strictFunctionTypes

boolean

default:"true if strict"

When assigning functions, check to ensure parameters and the return values are subtype-compatible.

tsc --strictFunctionTypes

Diagnostic Options

--pretty

boolean

default:"true"

Enable color and formatting in TypeScript’s output to make compiler errors easier to read.

tsc --pretty

--diagnostics

boolean

default:"false"

Output compiler performance information after building.

tsc --diagnostics

--extendedDiagnostics

boolean

default:"false"

Output more detailed compiler performance information after building.

tsc --extendedDiagnostics

--listFiles

boolean

default:"false"

Print all of the files read during the compilation.

tsc --listFiles

--explainFiles

boolean

default:"false"

Print files read during the compilation including why it was included.

tsc --explainFiles

--traceResolution

boolean

default:"false"

Log paths used during the moduleResolution process.

tsc --traceResolution

Help & Version

--help

boolean

default:"false"

Print this help message.Aliases: -h, -?

tsc --help
tsc -h

--version

boolean

default:"false"

Print the compiler’s version.Aliases: -v

tsc --version
tsc -v

--all

boolean

default:"false"

Show all compiler options.

tsc --all

Real-World Examples

Basic Compilation

Compile a TypeScript file to JavaScript:

tsc index.ts

Output:

index.js

Development Build

Compile with source maps and watch mode for development:

tsc --sourceMap --watch --pretty

Output:

[12:00:00 AM] Starting compilation in watch mode...
[12:00:03 AM] Found 0 errors. Watching for file changes.

Production Build

Compile for production with optimizations:

tsc --removeComments --declaration --sourceMap --outDir dist/

Output:

dist/
  ├── index.js
  ├── index.js.map
  └── index.d.ts

Type Checking Only

Check types without emitting files:

tsc --noEmit

Output:

src/utils.ts:15:7 - error TS2322: Type 'string' is not assignable to type 'number'.

15   let x: number = "hello";
         ^

Found 1 error.

Project References

Build a project with references:

tsc --build --verbose

Output:

[12:00:00 AM] Projects in this build: 
    * packages/core/tsconfig.json
    * packages/utils/tsconfig.json
    * tsconfig.json

[12:00:00 AM] Project 'packages/core/tsconfig.json' is up to date
[12:00:01 AM] Project 'packages/utils/tsconfig.json' is up to date

Exit Codes

success

Compilation succeeded with no errors.

error

Compilation failed with type errors.

error

Invalid command-line arguments.

Performance Tips

Use --incremental to speed up subsequent builds by saving compilation information.

Use --skipLibCheck to skip type checking of declaration files and speed up compilation.

Use project references with --build for large monorepo projects to enable incremental builds.

Common Errors

error TS5023: Unknown compiler option ‘xxx’Check the option name for typos. Use tsc --help to see all available options.

error TS5057: Cannot find a tsconfig.json file at the specified directoryEnsure tsconfig.json exists in the specified directory or use tsc --init to create one.

Source Code Reference

The TypeScript compiler implementation:

Main entry point: src/tsc/tsc.ts:24
Command-line parser: src/compiler/commandLineParser.ts
Build mode: src/compiler/builder.ts

The tsc binary (bin/tsc) is a wrapper that loads the compiled compiler from lib/tsc.js.

Get Started

CLI Commands

Configuration

Compiler

Advanced

tsc - TypeScript Compiler

Installation

Basic Usage

Command-Line Options

Project Configuration

Build Options

Target & Module Options

Emit Options

Type Checking Options

Diagnostic Options

Help & Version

Real-World Examples

Basic Compilation

Development Build

Production Build

Type Checking Only

Project References

Exit Codes

Performance Tips

Common Errors

Source Code Reference

Build docs developers (and LLMs) love

Get Started

CLI Commands

Configuration

Compiler

Advanced

​Installation

​Basic Usage

​Command-Line Options

​Project Configuration

​Build Options

​Target & Module Options

​Emit Options

​Type Checking Options

​Diagnostic Options

​Help & Version

​Real-World Examples

​Basic Compilation

​Development Build

​Production Build

​Type Checking Only

​Project References

​Exit Codes

​Performance Tips

​Common Errors

​Source Code Reference

Build docs developers (and LLMs) love

Installation

Basic Usage

Command-Line Options

Project Configuration

Build Options

Target & Module Options

Emit Options

Type Checking Options

Diagnostic Options

Help & Version

Real-World Examples

Basic Compilation

Development Build

Production Build

Type Checking Only

Project References

Exit Codes

Performance Tips

Common Errors

Source Code Reference