tsc

The TypeScript compiler executable. tsc reads .ts / .tsx / .js source files and a tsconfig.json configuration, type-checks them, runs the transformer pipeline, and emits .js, .d.ts, and source-map output.

Purpose

tsc is a thin shell around the compiler. Its source is just 24 lines (src/tsc/tsc.ts): hook up logging, enable source maps in development, set blocking I/O, then call ts.executeCommandLine(ts.sys, ts.noop, ts.sys.args). All of the heavy lifting — argument parsing, project discovery, watch mode, build mode, emit — is implemented in src/compiler/.

Directory layout

src/tsc/
├── _namespaces/      # generated namespace barrel
├── tsc.ts            # 24-line entry point
└── tsconfig.json     # TS project config

Entry point

src/tsc/tsc.ts does six things:

1. Wire Debug.loggingHost so deprecation messages go to ts.sys.write.
2. Enable detailed debug formatting when Debug.isDebugging is true.
3. Enable Node's source-map support in NODE_ENV=development.
4. Force blocking stdout via ts.sys.setBlocking() (avoids truncated output on exit).
5. Call ts.executeCommandLine(ts.sys, ts.noop, ts.sys.args).

executeCommandLine lives in src/compiler/executeCommandLine.ts (1,500+ lines). It owns:

• --help, --version, --init
• --watch mode (delegates to createWatchProgram in src/compiler/watchPublic.ts)
• --build / -b (delegates to createSolutionBuilder in src/compiler/tsbuildPublic.ts)
• --listFiles, --listFilesOnly, --showConfig, --explainFiles
• --diagnostics, --extendedDiagnostics, --generateTrace
• All of the standard tsc.js defaults applied when no tsconfig.json is found

For the tsconfig.json parsing path itself, see src/compiler/commandLineParser.ts and systems/command-line-and-config.

How it works

A typical tsc -p ./tsconfig.json invocation flows like this:

graph TD
    A["bin/tsc"] --> B["lib/tsc.js: ts.executeCommandLine"]
    B --> C{"--watch?"}
    C -->|no| D["createProgram"]
    C -->|yes| W["createWatchProgram (watchPublic.ts)"]
    B --> E{"--build?"}
    E -->|yes| F["createSolutionBuilder (tsbuildPublic.ts)"]
    D --> G["program.emit"]
    F --> G
    W --> G
    G --> H["TS files → checker → transformers → emitter"]
    H --> I["write .js / .d.ts / .map / .tsbuildinfo"]

The watch and build paths reuse the same primitives — both create a sequence of Program objects and call program.emit(). The difference is in how they invalidate and rebuild. See systems/watch-and-builder and systems/build-mode.

Key abstractions

Symbol	File	Role
executeCommandLine	src/compiler/executeCommandLine.ts	Top-level CLI dispatcher
createProgram	src/compiler/program.ts	One-shot Program construction
createWatchProgram	src/compiler/watchPublic.ts	Watch-mode loop
createSolutionBuilder	src/compiler/tsbuildPublic.ts	tsc -b orchestration
parseCommandLine	src/compiler/commandLineParser.ts	CLI flag → CompilerOptions
parseJsonConfigFileContent	src/compiler/commandLineParser.ts	tsconfig.json → ParsedCommandLine
ts.sys	src/compiler/sys.ts	Node-/browser-portable filesystem host

Integration points

• Receives flags from the user shell.
• Reads files via ts.sys (Node fs).
• Writes .js, .d.ts, source maps, .tsbuildinfo directly.
• Writes diagnostics to stderr via formatDiagnosticsWithColorAndContext.
• In watch mode, registers chokidar-style watchers via ts.sys.watchFile / ts.sys.watchDirectory.
• Optionally writes Chrome-trace JSON via --generateTrace (see src/compiler/tracing.ts).

Entry points for modification

Most user-visible tsc behaviour changes live in src/compiler/executeCommandLine.ts (CLI wiring), src/compiler/commandLineParser.ts (option definitions and validation), and src/compiler/program.ts (the orchestration). New compiler options must be added to the optionDeclarations and optionsForBuild/optionsForWatch tables in commandLineParser.ts, with corresponding diagnostic message keys in src/compiler/diagnosticMessages.json.

For watch/build behaviour, edit src/compiler/watchPublic.ts, src/compiler/watch.ts (formatting helpers), and src/compiler/tsbuildPublic.ts.

See also: systems/program, systems/watch-and-builder, systems/build-mode.