TypeScript Compiler Configuration

The tsconfig.json options that decide what the compiler catches and how fast it catches it.

Mindset

Keep strict: true as the non-negotiable baseline and treat every additional strictness flag (noUncheckedIndexedAccess, exactOptionalPropertyTypes, noImplicitReturns) as a default-on decision, not an opt-in one — the cost of a flag is some extra narrowing at the call sites it affects, and the cost of not having it is a defect the compiler could have caught but didn't. Never disable a strict-mode finding with @ts-ignore or strict: false; the defect it surfaced is still there, you've only removed the compiler's ability to tell you about it. When type-checking is slow, profile before guessing — tsc --extendedDiagnostics and project references usually explain the slowdown faster than trimming include patterns at random.

When to Apply

Use this skill when:

• Bootstrapping a tsconfig.json for a new project
• Deciding which strictness flags to enable beyond the strict bundle
• Debugging a module-resolution error (Cannot find module, wrong resolution strategy for ESM/bundler setups)
• Diagnosing and fixing slow tsc --noEmit runs

Use When

• "What should my tsconfig.json look like for a new Node/ESM project?"
• "Which strictness flags should I turn on beyond strict: true?"
• "Why is TypeScript not resolving this module the way I expect?"
• "Why is type-checking so slow, and how do I speed it up?"

Scope

In Scope

• tsconfig.json structure and common option choices.
• Strict-mode flags and what each one catches.
• Module resolution strategies (node, bundler, node16/nodenext) and their trade-offs.
• Diagnosing and improving type-checking performance.

Out of Scope

• Type-system design (generics, conditional types, unions) — see the sibling typescript-type-system skill.
• Runtime validation and type guards — see the sibling typescript-type-guards and typescript-practices skills.
• Build-pipeline or bundler configuration unrelated to the TypeScript compiler itself.

When NOT to Use

Do not use this skill for end-to-end test framework setup, CI pipeline configuration, or bundler configuration that isn't a tsconfig.json compiler option. Do not use it as a substitute for running tsc --noEmit — this skill explains what a setting does, but the compiler is the source of truth on whether the project actually type-checks under it.

Quick Commands

Type Check

npx tsc --noEmit

Diagnose Slow Type-Checking

npx tsc --noEmit --extendedDiagnostics

Generate a tsconfig.json

npx tsc --init

Anti-Patterns

NEVER disable a strict-mode finding instead of fixing the underlying type model

WHY: the defect strict mode caught is still present in the code; @ts-ignore and strict: false only remove the compiler's ability to report it.

BAD:

{ "compilerOptions": { "strict": false } }

GOOD:

{ "compilerOptions": { "strict": true, "noUncheckedIndexedAccess": true } }

NEVER set strict: true and stop there when the project can afford more

WHY: strict is a floor, not a ceiling — flags like noUncheckedIndexedAccess and exactOptionalPropertyTypes catch real classes of bugs strict alone leaves open.

BAD:

{ "compilerOptions": { "strict": true } }

GOOD:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  }
}

NEVER guess at a performance fix before profiling

WHY: trimming include patterns or splitting files at random can miss the actual cause (often deep conditional-type recursion or an oversized project graph) while adding maintenance overhead for no measured gain.

BAD: Randomly excluding directories from include because "it feels slow."

GOOD: Run tsc --noEmit --extendedDiagnostics first, then act on what it reports (files checked, instantiation count, memory).

References

• TSConfig Reference
• TypeScript Handbook: Compiler Options