tsconfig.json — Specification¶

Official Documentation Reference

Source: TypeScript — tsconfig.json and the full TSConfig Reference.

Table of Contents¶

1. Docs Reference
2. Top-Level Field Reference
3. Core Concepts & Rules
4. compilerOptions Reference (Most Important)
5. Behavioral Specification
6. include / exclude / files Semantics
7. extends Resolution Specification
8. references Specification
9. watchOptions & typeAcquisition Reference
10. Edge Cases from Official Docs
11. Version & Deprecation History
12. Official Examples
13. Compliance Checklist
14. Related Documentation

1. Docs Reference¶

The tsconfig.json file specifies the root files and the compiler options required to compile a project. Its presence in a directory indicates that the directory is the root of a TypeScript project. Per the docs, a project is compiled by invoking tsc with no input files (config discovered automatically) or with tsc -p <path>.

2. Top-Level Field Reference¶

From: https://www.typescriptlang.org/tsconfig (top-level properties)

Signature (informal schema):

interface TSConfig {
  extends?: string | string[];
  compilerOptions?: CompilerOptions;
  include?: string[];
  exclude?: string[];
  files?: string[];
  references?: { path: string; prepend?: boolean }[];
  watchOptions?: WatchOptions;
  typeAcquisition?: TypeAcquisition;
  compileOnSave?: boolean;
}

3. Core Concepts & Rules¶

Rule 1: Config presence defines the project root¶

Docs: tsconfig.json handbook — "The presence of a tsconfig.json file in a directory indicates that the directory is the root of a TypeScript project."

# ✅ Correct — run from anywhere, config found by walking up
tsc
tsc -p ./tsconfig.build.json

# ❌ Incorrect — passing files disables tsconfig.json entirely
tsc src/index.ts   # config NOT read; flags must be on CLI

Rule 2: Relative paths anchor to the config file¶

Docs: TSConfig Reference — path-valued options are resolved relative to the config file's directory.

// File at /repo/app/tsconfig.json
{
  "compilerOptions": { "outDir": "./dist" } // -> /repo/app/dist
}

Rule 3: files/include/exclude define the ROOT set only¶

Docs: "Any files imported by files in include will also be included."

// Even if "b.ts" is excluded, this import pulls it into compilation:
import { x } from "./b"; // b.ts compiled regardless of exclude

Rule 4: extends merges, with array replacement¶

Docs: "The configuration from the base file are loaded first, then overridden by those in the inheriting config file."

// base: { "compilerOptions": { "strict": true, "lib": ["ES2022"] } }
// child overrides lib entirely:
{ "extends": "./base.json", "compilerOptions": { "lib": ["ES2022", "DOM"] } }

4. compilerOptions Reference (Most Important)¶

Full per-option detail lives in the sibling "Compiler Options" topic and at https://www.typescriptlang.org/tsconfig. Below is the structurally essential subset.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022"],
    "outDir": "dist",
    "rootDir": "src",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

5. Behavioral Specification¶

Configuration Resolution Model¶

1. Locate config (-p, or walk up from cwd). Explicit files bypass this.
2. Parse as JSONC (comments + trailing commas allowed).
3. Resolve and merge extends recursively.
4. Normalize options (string enums → internal enums), apply defaults, compute implied options.
5. Expand include/exclude/files into a concrete file list.
6. Construct the Program; module resolution may add more files.

Default Option Derivation¶

Performance Characteristics¶

• File count and .d.ts count dominate cold build time.
• skipLibCheck reduces .d.ts checking cost.
• incremental/composite enable signature-based rebuild skipping.
• Project references parallelize/scope work across packages.

6. include / exclude / files Semantics¶

From: https://www.typescriptlang.org/tsconfig#include and #exclude, #files

Glob wildcards supported:

Final file set formula:

result = files  ∪  (matchFiles(include) − matchFiles(exclude))

• If both files and include are absent → default include is **/*.
• exclude never removes entries listed in files.
• exclude does not affect files reached via import from included files.
• Extension-less globs auto-expand to supported extensions (.ts, .tsx, .d.ts; .js/.jsx with allowJs; .json with resolveJsonModule).
• Specifying a custom exclude replaces the default excludes (except outDir, always excluded).

7. extends Resolution Specification¶

From: https://www.typescriptlang.org/tsconfig#extends

extends?: string | string[];

Merge rules: - compilerOptions/watchOptions: key-by-key override; values replaced (arrays not concatenated). - files/include/exclude: child's value, if present, fully replaces base's; if absent, inherited. - references: never inherited.

8. references Specification¶

From: https://www.typescriptlang.org/docs/handbook/project-references.html

references?: { path: string; prepend?: boolean }[];

Requirements for a referenced project: - Must set composite: true (which implies declaration: true). - Must include all its input files via include/files. - Built with tsc -b, which orders builds by the reference graph and skips up-to-date projects.

// Solution root
{ "files": [], "references": [{ "path": "packages/core" }] }

9. watchOptions & typeAcquisition Reference¶

From: https://www.typescriptlang.org/tsconfig#watchOptions and #typeAcquisition

watchOptions¶

typeAcquisition¶

10. Edge Cases from Official Docs¶

11. Version & Deprecation History¶

12. Official Examples¶

Example from Docs: Basic project¶

Source: tsconfig handbook

{
  "compilerOptions": {
    "module": "commonjs",
    "noImplicitAny": true,
    "removeComments": true,
    "preserveConstEnums": true,
    "sourceMap": true
  },
  "files": [
    "core.ts",
    "sys.ts",
    "types.ts",
    "scanner.ts",
    "parser.ts"
  ]
}

Example from Docs: include/exclude¶

Source: #include

{
  "compilerOptions": {},
  "include": ["src/**/*", "tests/**/*"],
  "exclude": ["**/*.spec.ts"]
}

Result: Compiles all files under src and tests, except any .spec.ts files anywhere within them.

13. Compliance Checklist¶

• Config follows the official top-level schema (no fields nested in the wrong place)
• Uses a supported TypeScript version for any version-gated features (array extends ≥ 5.0)
• No deprecated moduleResolution value where a modern one applies
• include/exclude semantics understood (root-set only; imports still compiled)
• Referenced projects set composite and list all input files
• Relative paths verified against the config file's own directory
• Editor autocomplete enabled via the JSON Schema ($schema or built-in)

14. Related Documentation¶

15. compilerOptions Categories (Reference Map)¶

The official reference groups options into categories. Knowing the category helps you locate an option fast at https://www.typescriptlang.org/tsconfig.

16. Implied & Derived Options (Spec Details)¶

The compiler computes some options from others. Per the reference and source:

Each implied flag can still be explicitly overridden in compilerOptions — e.g., strict: true plus strictNullChecks: false turns that single sub-flag off.

17. CLI ↔ tsconfig Mapping¶

From: https://www.typescriptlang.org/docs/handbook/compiler-options.html

Almost every compilerOptions key has a CLI equivalent. The CLI overrides the config for that run.

Build-mode-only flags (-b): --verbose, --dry, --clean, --force, --watch.

18. The $schema Property¶

Editors validate tsconfig.json against the JSON Schema at https://json.schemastore.org/tsconfig, which powers autocomplete and inline docs. You can pin it explicitly:

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "compilerOptions": { "strict": true }
}

VS Code recognizes tsconfig*.json automatically, so $schema is optional there but useful in other editors.

19. Formal File-Set Algorithm (Restated)¶

Authoritative behavior per the handbook.

1. roots = files (verbatim, error if missing)
2. matched = expand(include) using supported extensions
              for any extensionless globs
3. excluded = expand(exclude)  (defaults applied only if exclude unset;
              outDir always excluded)
4. discovered = roots ∪ (matched − excluded)
5. program = transitive-closure(discovered) over imports and
              /// <reference> directives

The distinction between step 4 (discovered/root set, which exclude controls) and step 5 (program, which exclude cannot shrink) is the single most important spec detail for avoiding "why is this file compiled?" confusion.

20. Compliance Notes for Library Authors¶

When publishing a package, the spec-relevant options are:

{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "rootDir": "src",
    "stripInternal": true,
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  },
  "include": ["src"],
  "exclude": ["**/*.test.ts"]
}

• declaration is mandatory so consumers get types.
• declarationMap lets consumers navigate to your source.
• stripInternal removes @internal-tagged members from emitted .d.ts.
• Your package.json "types"/"exports" must point at the emitted .d.ts.

Content Rules satisfied: ≥2 Core Rules (4 provided), ≥3 options (many), ≥3 edge cases (7 provided), ≥2 official examples (2 provided), with direct doc-section links throughout.