tsc — Specification¶

Official Documentation Reference

Source: TypeScript Handbook — Compiler Options and TSConfig Reference

Table of Contents¶

1. Docs Reference
2. CLI Reference
3. Core Concepts & Rules
4. Compiler Options Reference
5. Behavioral Specification
6. Exit Codes & Error Codes
7. Platform / Runtime Compatibility
8. Edge Cases from Official Docs
9. Version & Deprecation History
10. Official Examples
11. Compliance Checklist
12. Related Documentation

1. Docs Reference¶

The tsc binary is installed by the typescript npm package. Running tsc --help prints a curated subset of options; tsc --all prints every option the build of tsc supports.

tsc --version          # Version 5.4.5
tsc --help             # common options
tsc --all              # full option list for this tsc version

2. CLI Reference¶

From: Compiler Options — Using the CLI

Invocation forms¶

tsc                         # compile the project found via tsconfig.json
tsc file.ts                 # compile a single file with DEFAULT options (ignores tsconfig)
tsc file1.ts file2.ts       # compile multiple files (default options)
tsc -p <path|dir>           # compile using a specific tsconfig (or dir containing one)
tsc --build [proj...]       # build mode: orchestrate project references
tsc --init                  # generate a starter tsconfig.json

Top-level CLI flags (selection)¶

Build-mode-only flags¶

tsc --build --verbose
tsc --build --dry
tsc --build --force
tsc --build --clean

3. Core Concepts & Rules¶

Rule 1: A file argument disables tsconfig.json¶

Docs: tsconfig.json — "When input files are specified on the command line, tsconfig.json files are ignored."

# ✅ Correct — uses tsconfig.json (its outDir, strict, etc.)
tsc
tsc -p tsconfig.json

# ❌ Incorrect for a project — ignores tsconfig.json, uses defaults
tsc src/index.ts

Rule 2: CLI options override tsconfig.json for that run¶

Docs: Compiler Options

A flag given on the command line takes precedence over the same option in the config, but only for that invocation; it is not persisted.

# tsconfig has target es5; this single run emits es2022
tsc --target es2022

Rule 3: --build requires composite projects¶

Docs: Project References

Every project referenced in build mode must set "composite": true, which implies declaration: true and forces .tsbuildinfo to be written.

// ✅ Correct
{ "compilerOptions": { "composite": true, "declaration": true, "outDir": "dist" } }

// ❌ Incorrect — referenced but not composite -> build error TS6306
{ "compilerOptions": { "outDir": "dist" } }

Rule 4: noEmit and composite are mutually exclusive¶

Docs: TSConfig Reference — composite

Because composite requires emitting declarations, it cannot be combined with noEmit.

Rule 5: Emit happens even with errors unless told otherwise¶

Docs: TSConfig Reference — noEmitOnError

By default tsc writes output even when diagnostics are reported. Set noEmitOnError: true to suppress output when any error exists.

4. Compiler Options Reference¶

From: TSConfig Reference

Emit & output¶

Language & module¶

Type-checking strictness¶

Performance & build¶

// A representative production tsconfig
{
  "compilerOptions": {
    "target": "es2022",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "incremental": true,
    "skipLibCheck": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "noEmitOnError": true
  },
  "include": ["src"]
}

5. Behavioral Specification¶

Compilation model¶

tsc constructs a Program from the resolved root files, resolves all module imports (pulling in lib and @types), then type-checks and (optionally) emits. A single tsc invocation produces one Program; tsc --build produces one per referenced project.

File discovery precedence¶

1. If file arguments are passed → exactly those files, default options, no tsconfig.
2. Else -p <path> → that config.
3. Else the nearest tsconfig.json searching upward from the cwd.

files (explicit list) and include/exclude (globs) determine the input set; exclude only filters include, never files.

Emit behavior¶

• One .js per input module (no bundling, except legacy outFile).
• .d.ts emitted when declaration (or emitDeclarationOnly) is on.
• Output location = outDir + the path of the input relative to rootDir.
• With noEmit, the emitter is skipped entirely.

Watch behavior¶

--watch keeps the process alive, reuses unchanged SourceFiles, and re-checks the affected set on each change. watchOptions in tsconfig tune the file-system watching strategy.

Performance characteristics¶

Per --diagnostics, the Check time phase typically dominates. skipLibCheck, incremental, and project references are the primary documented levers. --generateTrace localizes hot spots to specific expressions/types.

6. Exit Codes & Error Codes¶

Exit codes¶

tsc --noEmit; echo $?   # 0 or 2 most commonly

Error-code format¶

Every diagnostic has the form:

<file>(<line>,<col>): error TS<number>: <message>

or, in pretty mode:

<file>:<line>:<col> - error TS<number>: <message>

The full list of codes lives in the compiler's diagnosticMessages.json. Frequently seen: TS2304, TS2307, TS2322, TS2345, TS2339, TS2531/2532, TS2554, TS2589, TS6133, TS6202, TS6306, TS18003.

7. Platform / Runtime Compatibility¶

The target/lib options decide the output's runtime compatibility, independent of the Node version running tsc itself.

8. Edge Cases from Official Docs¶

9. Version & Deprecation History¶

Deprecated: importsNotUsedAsValues and preserveValueImports (use verbatimModuleSyntax); --out (use outFile); legacy suppressImplicitAnyIndexErrors-style escape hatches are discouraged.

10. Official Examples¶

Example from Docs: Initialize and build¶

Source: Project References — Build mode

tsc --init                 # create tsconfig.json
tsc                        # compile per config
tsc --build --verbose      # build references with logging

Result:

Projects in this build:
    * tsconfig.json

Project 'tsconfig.json' is out of date because output file 'dist/index.js'
  does not exist

Building project '/path/tsconfig.json'...

Example from Docs: Type-check only¶

Source: Compiler Options — noEmit

tsc --noEmit

Result:

Found 0 errors.

Example from Docs: Show resolved config¶

Source: Compiler Options — showConfig

tsc --showConfig

Result:

{
  "compilerOptions": { "strict": true, "target": "es2022", "outDir": "./dist" },
  "files": ["./src/index.ts"]
}

10b. Canonical Workflows (Reference)¶

Quick-reference command recipes that map to the documented behaviors above.

Initialize and build a project¶

tsc --init            # scaffold tsconfig.json
tsc                   # compile per config
node dist/index.js    # run output

Type-check only (CI gate)¶

tsc --noEmit --pretty false
echo $?               # 0 clean, 2 errors

Watch during development¶

tsc --watch                 # watch + emit
tsc --noEmit --watch        # watch + check only

Multi-config (dev vs build)¶

tsc -p tsconfig.json          # dev/check config
tsc -p tsconfig.build.json    # production emit config

Project references (monorepo)¶

tsc --build                 # build the whole graph
tsc --build --verbose       # explain each project's status
tsc --build --dry           # preview, build nothing
tsc --build --force         # ignore up-to-date status
tsc --build --clean         # delete all outputs

Library emit¶

tsc --declaration --declarationMap          # .js + .d.ts + maps
tsc --emitDeclarationOnly --declaration      # types only (bundler emits JS)

Performance investigation¶

tsc --noEmit --diagnostics
tsc --noEmit --extendedDiagnostics
tsc --noEmit --generateTrace .trace
npx @typescript/analyze-trace .trace

Inspection / debugging¶

tsc --showConfig            # fully-resolved config
tsc --noEmit --listFiles    # every included file
tsc --noEmit --explainFiles # included files + reasons
tsc --noEmit --traceResolution   # module-resolution decisions

10c. Option Interaction Matrix (Reference)¶

Selected option combinations that the docs call out as required or forbidden.

11. Compliance Checklist¶

• Uses a supported typescript version, installed locally (pinned in package.json).
• Project builds with bare tsc/tsc -p/tsc --build (no stray file-argument runs).
• tsc --noEmit runs as a CI gate; exit code is not masked.
• strict: true enabled; no undocumented strictness opt-outs.
• composite set on all referenced projects; reference graph is acyclic.
• noEmitOnError set where shipping broken JS is unacceptable.
• No deprecated options (importsNotUsedAsValues, --out); migrated to current equivalents.
• forceConsistentCasingInFileNames enabled to avoid cross-OS bugs.

12. Related Documentation¶

Content Rules applied: - Direct links to specific doc sections, not just the homepage. - Official option types/defaults from the TSConfig reference. - Deprecated options documented with migration paths. - Edge cases sourced from official handbook/reference pages.