Deep tsconfig.json

Strictness and Checking Options

"strict": true is the floor; these flags catch the defects that still slip past it:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "verbatimModuleSyntax": true
  }
}

noUncheckedIndexedAccess types arr[0] as T | undefined, forcing bounds checks. exactOptionalPropertyTypes stops { a: undefined } from satisfying { a?: string }. verbatimModuleSyntax preserves import type elision exactly as written, which keeps side-effect-only imports from vanishing under isolatedModules transpilers.

Module Resolution and Paths

module and moduleResolution must agree with the runtime:

{ "module": "nodenext", "moduleResolution": "nodenext" }
{ "module": "esnext",  "moduleResolution": "bundler" }

Under nodenext, relative imports need explicit .js extensions and package exports are honored, matching Node ESM. bundler allows extensionless imports because a bundler resolves them. paths maps aliases for the type checker:

{ "paths": { "@app/*": ["./src/*"] } }

Paths are type-level only — Jest, Vite, and Node need matching alias config or types compile while runtime resolution fails.

Project References and Build Flags

Project references split a repo into independently built pieces:

{ "compilerOptions": { "composite": true, "declaration": true, "outDir": "dist" },
  "references": [{ "path": "../core" }] }

composite requires declaration and a fixed rootDir; consumers then import via .d.ts outputs instead of re-typechecking sources. tsc -b builds the dependency graph in order and skips up-to-date projects (tracked in .tsbuildinfo), which is what makes monorepo typechecking incremental.

Pitfall: references govern TypeScript only — bundlers and test runners still need their own resolution, and a stale outDir after refactoring rootDir produces confusing "file not found" errors.