tsconfig Deep Dive

Concept#

The beginner framing: tsconfig.json isn't just "the file that makes tsc work", its settings meaningfully change what code is accepted, how strictly types are checked, and how modules resolve, often in ways that matter far more than which specific syntax features are used in the code itself.

The strict family: one flag, several distinct checks#

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

strict: true is shorthand for enabling several individual flags together, noImplicitAny, strictNullChecks, strictFunctionTypes, strictPropertyInitialization, strictBindCallApply, noImplicitThis, alwaysStrict, and useUnknownInCatchVariables, among others. Two of the most impactful individually:

function greet(name) { return "hi " + name; } // implicit `any` parameter

error TS7006: Parameter 'name' implicitly has an 'any' type.

Confirmed by compiling with noImplicitAny on vs. off: without it, an untyped parameter silently becomes any with no warning at all; with it enabled, this becomes a real compile error, forcing every parameter to have an inferable or explicit type, closing off a common, easy way for type safety to quietly leak out of otherwise-typed code.

function getLength(s: string) { return s.length; }
let maybeNull: string | null = null;
getLength(maybeNull); // does this compile?

error TS2345: Argument of type 'null' is not assignable to parameter of type 'string'.

Confirmed by compiling with strictNullChecks enabled: null and undefined are no longer silently assignable to every other type, a string | null genuinely isn't a string, and passing one where a plain string is expected is now a real, caught error. Without strictNullChecks, this same code compiles without complaint, which is exactly the gap that leads to the classic "Cannot read properties of null" runtime crash.

moduleResolution: "bundler", the modern default for bundled projects#

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

Covered in depth in Modules & Namespaces, worth a brief recap here in its proper configuration context: "bundler" resolution matches how modern build tools (Vite, webpack, esbuild) actually resolve modules, including allowing extensionless relative imports. It's the modern default recommendation specifically for projects that go through a bundler rather than running directly under Node.

Project references: composite builds for multi-package projects#

// core/tsconfig.json
{ "compilerOptions": { "composite": true, "outDir": "./dist" } }

// app/tsconfig.json
{
  "references": [{ "path": "../core" }],
  "compilerOptions": { "outDir": "./dist" }
}

tsc -b app  # builds core FIRST (as a dependency), then app

Confirmed by actually running this exact two-package setup: tsc -b (build mode) with references correctly built the referenced core project first, emitting its own .d.ts files and a .tsbuildinfo cache, before building app, which imports from core. This is TypeScript's built-in mechanism for multi-package projects/monorepos: each package gets its own tsconfig.json with composite: true, dependencies are declared via references, and tsc -b handles the correct build order and incremental rebuilding automatically, only recompiling packages whose inputs actually changed.

${configDir}, stable since TypeScript 5.5#

// tsconfig.json
{
  "compilerOptions": {
    "outDir": "${configDir}/dist"
  }
}

Confirmed by building a real project with this exact setting: ${configDir} resolves to the directory containing the tsconfig.json file itself, regardless of the current working directory tsc happens to be invoked from. This matters specifically for shared, extended base configs, a common pattern in monorepos where multiple packages extend a shared tsconfig.base.json, since without ${configDir}, a relative path like "./dist" in that shared base config would resolve relative to wherever it's extended from, not the individual package's own directory, which is very often not the intended behavior.

Try It#

Predict the outcome before checking the solution.

// tsconfig.base.json (shared, extended by multiple packages)
{ "compilerOptions": { "outDir": "./dist" } }

// packages/foo/tsconfig.json
{ "extends": "../../tsconfig.base.json" }

Where does foo's compiled output actually end up, given the base config's outDir: "./dist"?

Implement It Yourself#

Sketch a minimal monorepo tsconfig setup combining a shared base config with ${configDir} and per-package project references:

// tsconfig.base.json
{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "bundler",
    "outDir": "${configDir}/dist",
    "composite": true
  }
}

// packages/core/tsconfig.json
{ "extends": "../../tsconfig.base.json", "include": ["src/**/*.ts"] }

// packages/app/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "references": [{ "path": "../core" }],
  "include": ["src/**/*.ts"]
}

This combines every mechanism covered in this topic: strict for the shared safety baseline, moduleResolution: "bundler" for the shared module behavior, ${configDir} so each package's outDir correctly points at its own directory rather than the shared base config's, and references wiring up the correct build order between packages.

Under the Hood#

The strict family's individual flags each connect to concepts covered elsewhere, strictNullChecks is what makes the unknown-vs-any distinction from Types meaningful in practice (without it, null/undefined silently satisfy everything, undermining a lot of the precision those types otherwise provide), and noImplicitAny is the configuration-level enforcement of the "annotate function parameters" rule from TypeScript Basics's inference-first philosophy, without it, that rule is just a convention; with it, it's a checked requirement.

Common Mistakes#

1. Assuming strict: true is one single, atomic check#

{ "compilerOptions": { "strict": true } } // this is actually SEVERAL flags at once

Treating strict as one opaque switch makes it harder to reason about exactly what changed when enabling or disabling it, knowing it's a bundle of specific, individually-toggleable flags (noImplicitAny, strictNullChecks, and others) makes debugging a "why did this suddenly start/stop erroring" question much more tractable.

2. Using a plain relative path in a shared base config, expecting per-package resolution#

// tsconfig.base.json
{ "compilerOptions": { "outDir": "./dist" } } // ❌ resolves relative to the EXTENDING file, not this one

Without ${configDir}, this always resolves relative to whichever config does the extending, often not the intended behavior for a genuinely shared setting meant to work consistently across many packages.

3. Not setting composite: true on a project meant to be referenced by others#

// core/tsconfig.json, meant to be used via project references
{ "compilerOptions": { "outDir": "./dist" } } // ❌ missing composite: true

Project references require the referenced project to have composite: true set, without it, tsc -b won't treat it as a valid reference target, and the multi-project build won't work as intended.

Best Practices#

• Enable strict: true for new projects by default, the individual checks it bundles catch a substantial fraction of real bugs at compile time, and retrofitting it onto a large existing codebase later is considerably more painful than starting with it.
• Use ${configDir} in shared base configs specifically for path-like settings (outDir, rootDir) that should resolve relative to each individual extending package, not the shared base file's own location.
• Set up project references for genuine multi-package monorepos, the incremental, correctly-ordered builds tsc -b provides are a real, tangible build-time benefit over treating the whole repo as one flat TypeScript project.
• Match moduleResolution deliberately to the actual runtime/bundler target, as covered in Modules & Namespaces, rather than leaving it at a default that doesn't match the real deployment environment.

Performance Tips#

• Project references with composite: true enable genuinely incremental builds, tsc -b only rebuilds packages whose actual inputs changed, which is a real, often substantial build-time win in a large monorepo compared to a full, flat recompilation on every change.
• ${configDir} and shared base configs have zero runtime effect, this is entirely a build-configuration and developer-experience concern, with no bearing on the compiled application's actual runtime behavior.