Compiler Options — Specification¶

Official Documentation Reference

Source: TypeScript TSConfig Reference — compilerOptions

Table of Contents¶

1. Docs Reference
2. Option Categories
3. Type Checking Options
4. Modules Options
5. Emit Options
6. Language and Environment Options
7. Interop and Projects Options
8. Defaults and Implications
9. Edge Cases from Official Docs
10. Version and Deprecation History
11. Official Examples
12. Compliance Checklist
13. Related Documentation

1. Docs Reference¶

The official reference groups options into categories. This page mirrors that grouping and gives the signature, default, and a precise behavioral note for each important option, with a direct link.

2. Option Categories¶

3. Type Checking Options¶

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

strict¶

Signature: "strict": boolean — Default: false

Umbrella flag. Enables noImplicitAny, strictNullChecks, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, noImplicitThis, useUnknownInCatchVariables, and alwaysStrict. Future strict-by-default flags may be added under it. You can enable strict and override any single member.

Docs: "enables a wide range of type checking behavior that results in stronger guarantees of program correctness."

The strict family¶

Additional checking flags (not in strict)¶

4. Modules Options¶

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

module¶

Signature: "module": "none" | "commonjs" | "amd" | "umd" | "system" | "es6"/"es2015" | "es2020" | "es2022" | "esnext" | "node16" | "node18" | "nodenext" | "preserve" — Default: depends on target (often commonjs for ES3/ES5, es2015+ otherwise; nodenext when moduleResolution is nodenext).

Sets the module syntax of emitted JavaScript. nodenext/node16 decide CJS vs ESM per file from package.json. preserve (5.4+) keeps import/export verbatim, leaving format to the bundler.

moduleResolution¶

Signature: "classic" | "node10"/"node" | "node16" | "nodenext" | "bundler" — Default: inferred from module.

The algorithm to locate modules. node16/nodenext honor package.json exports/imports/type. bundler (5.0+) mirrors node16 lookup but does not require file extensions in specifiers.

Resolution helpers¶

Docs note: "paths lets you re-map imports... these mappings are only performed at the type level; you need a loader at runtime."

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@app/*": ["src/*"] },
    "resolveJsonModule": true,
    "esModuleInterop": true
  }
}

5. Emit Options¶

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

{
  "compilerOptions": {
    "target": "ES2022",
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "importHelpers": true
  }
}

6. Language and Environment Options¶

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

lib common entries: ES5, ES2015–ES2023, ESNext, DOM, DOM.Iterable, WebWorker, ScriptHost. Setting lib replaces the target-derived default, so include both an ES version and any environment libs you need.

jsx values: - preserve — keep JSX, output .jsx (a bundler/Babel finishes it). - react — classic React.createElement calls (needs React in scope). - react-jsx — automatic runtime (_jsx from react/jsx-runtime); no React import needed (React 17+). - react-jsxdev — like react-jsx with dev-time checks.

7. Interop and Projects Options¶

From: https://www.typescriptlang.org/tsconfig#Projects_6255 and Interop Constraints

{
  "compilerOptions": {
    "composite": true,
    "incremental": true,
    "skipLibCheck": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true
  },
  "references": [{ "path": "../core" }]
}

8. Defaults and Implications¶

9. Edge Cases from Official Docs¶

10. Version and Deprecation History¶

11. Official Examples¶

Example: Recommended base (from @tsconfig/strictest)¶

Source: https://github.com/tsconfig/bases/blob/main/bases/strictest.json

{
  "compilerOptions": {
    "strict": true,
    "allowUnusedLabels": false,
    "allowUnreachableCode": false,
    "exactOptionalPropertyTypes": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitOverride": true,
    "noImplicitReturns": true,
    "noPropertyAccessFromIndexSignature": true,
    "noUncheckedIndexedAccess": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "checkJs": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Example: Modern Node 20 (from @tsconfig/node20)¶

Source: https://github.com/tsconfig/bases/blob/main/bases/node20.json

{
  "compilerOptions": {
    "lib": ["es2023"],
    "module": "node16",
    "target": "es2022",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "moduleResolution": "node16"
  }
}

Result: A strict, modern Node configuration with per-file CJS/ESM resolution from package.json.

12. Compliance Checklist¶

• strict: true (or @tsconfig/strictest) is the baseline.
• target, module, moduleResolution are set explicitly and mutually consistent.
• lib includes a matching ES version plus required environment libs.
• Libraries emit declaration + declarationMap.
• Bundler-emitted projects set isolatedModules + verbatimModuleSyntax.
• Deprecated importsNotUsedAsValues/preserveValueImports are not used.
• paths aliases have a matching runtime resolver.
• composite projects fully cover inputs via include/files.

13. Related Documentation¶

14. Per-Option Behavioral Specification¶

Detailed, doc-sourced semantics for the highest-impact options.

strict — exact behavior¶

Docs: "The strict flag enables a wide range of type checking behavior... When strict is on, all of the following are set to true by default; you may turn any of them off individually."

The set is fixed per TypeScript version and may grow in major releases. As of TypeScript 5.x it is the eight flags listed in section 3. Because new strict flags can be added under it, strict: true is intentionally a moving target — upgrading TypeScript may surface new (true) errors. Teams that want a frozen set enumerate the individual flags instead.

strictNullChecks — assignability rule¶

Docs: "null and undefined have their own distinct types and you'll get a type error if you try to use them where a concrete value is expected."

Formally: with the flag off, null and undefined are in the domain of every type T. With it on, they are removed from every T except any, unknown, void, and types that explicitly include them. Control-flow narrowing (computed from the binder's CFG) is the mechanism to recover a non-null type inside a guarded block.

noUncheckedIndexedAccess — result type rule¶

Docs: "adds undefined to any un-declared field in the type."

Applies to: element access obj[key] where the key is covered by an index signature, and array/tuple element access by a number. Does not apply to access of explicitly declared properties. The added | undefined is a checker-side type construction; emit is unaffected.

exactOptionalPropertyTypes — optionality rule¶

Docs: "with this enabled, TypeScript ... does not add undefined to the type of an optional property."

The checker tracks "this property is optional" separately from "this property's type contains undefined". Assigning the literal undefined to an optional property is rejected unless undefined is explicitly in the declared type. Reading an optional property still yields T | undefined (presence is not guaranteed).

module: "nodenext" — per-file format¶

Docs: "the module format of a particular file is determined by the type field in the nearest package.json."

A .mts file is always ESM; a .cts file is always CommonJS; a .ts file follows the nearest package.json "type" ("module" → ESM, otherwise CJS). Import specifiers must include file extensions for relative imports under this mode.

verbatimModuleSyntax — emit rule¶

Docs: "any imports or exports without a type modifier are left around. Anything that uses the type modifier is dropped entirely."

No type-directed elision occurs. This makes single-file transpilation deterministic. The flag is mutually exclusive with the deprecated importsNotUsedAsValues and preserveValueImports.

15. Compiler API Surface¶

Every tsconfig.json option corresponds to a field on the ts.CompilerOptions interface in the TypeScript Compiler API. Tools read and apply them programmatically:

import ts from "typescript";

const options: ts.CompilerOptions = {
  target: ts.ScriptTarget.ES2022,
  module: ts.ModuleKind.NodeNext,
  strict: true,
  noUncheckedIndexedAccess: true,
};

const program = ts.createProgram(["src/index.ts"], options);
const diagnostics = ts.getPreEmitDiagnostics(program);

Enum mappings worth knowing:

The string forms in tsconfig.json are case-insensitive; the API enums are canonical.

16. Mutually Exclusive and Dependent Options¶

17. Full Option Index by Category (Quick Reference)¶

Type Checking¶

Modules¶

Emit¶

Interop & Language/Environment¶

Projects¶

18. Notable Recently-Added Options¶

Content Rules satisfied: direct section links for every option group; defaults documented; deprecated options (importsNotUsedAsValues, preserveValueImports) flagged with migration to verbatimModuleSyntax; official @tsconfig/* examples included; edge cases sourced from the docs; behavioral specs quote the official reference.