tsc - TypeScript Compiler

Complete reference for the TypeScript compiler command-line interface

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

Installation

npm install -g typescript

Basic Usage

Compile a single file

tsc file.ts

tsc

tsc --project tsconfig.production.json

tsc --watch

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: -t

Valid 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: -m

Valid 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

0 · success

Compilation succeeded with no errors.

1 · error

Compilation failed with type errors.

2 · 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 directory

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