TypeScript tsconfig.json – The Path Alias Runtime Trap

Path aliases in tsconfig.json let you write clean imports like @/utils/dateHelpers instead of ../../../shared/utils/dateHelpers, but they only work during type-checking. The emitted JavaScript still contains the alias paths, which Node.js cannot resolve, causing ERR_MODULE_NOT_FOUND crashes at runtime. This trap is the most common silent failure in TypeScript projects — type-check passes, but production breaks. You must configure your bundler (Webpack, Vite, esbuild) or use a runtime resolver (tsconfig-paths, tsc-alias) to rewrite those paths in the output.

What tsconfig.json Actually Does (and Why 'tsc' Alone Isn't Enough)

When you run tsc in a TypeScript project, the compiler goes looking for a tsconfig.json in the current directory and walks up the folder tree until it finds one. That file is the contract between you and the compiler.

It does three things. First, it defines the root files — which source files are part of this compilation. Second, it controls compiler behaviour — strictness, output format, target JavaScript version. Third, it sets output destinations — where compiled .js files land, whether declaration files are generated, and whether source maps are emitted.

Why not just use CLI flags? Because flags don't scale. A real project might need 15 or more options. CLI flags can't be code-reviewed meaningfully, can't be shared across scripts, and change between npm scripts without anyone noticing. tsconfig.json makes your build reproducible — the same way a Dockerfile makes your server environment reproducible.

One subtlety: running tsc with explicit filenames on the command line (e.g. tsc src/index.ts) ignores your tsconfig.json entirely. TypeScript only reads the config when you run tsc without file arguments. This surprises a lot of developers.

# Step 1: Install TypeScript locally (always prefer local over global)
npm install --save-dev typescript

# Step 2: Let TypeScript generate a starter tsconfig with all options documented
npx tsc --init

# Step 3: Verify the compiler is reading your config (not guessing)
# This prints the resolved config TypeScript will actually use
npx tsc --showConfig

# Step 4: Type-check without emitting any JavaScript files
# Useful in CI to catch errors fast without cluttering the output folder
npx tsc --noEmit

The Compiler Options That Actually Matter — strict, target, module and Friends

tsconfig.json has over 100 options, but roughly 8 of them determine 90% of your project's behaviour. Let's walk through them with the context that's always missing from the docs.

strict: true is a single flag that enables eight separate checks: noImplicitAny, strictNullChecks, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, noImplicitThis, alwaysStrict, and useUnknownInCatchVariables. Turn on strict: true and you've turned on all of them at once. Most teams set this and never look back.

target tells TypeScript which JavaScript version to emit. Set target: 'ES2017' and TypeScript will downcompile async/await to Promise chains. Set target: 'ESNext' and it emits modern JS untouched. This is separate from what your runtime supports — so match it to your deployment environment (Node.js version, browser support matrix).

module controls how import/export statements are compiled. commonjs is right for Node.js. ESNext is right for bundlers like Vite or Webpack. Getting this wrong produces runtime errors that type-checking can't catch.

lib tells TypeScript which browser/runtime APIs exist. If you're targeting older browsers but your target is ES2020, you still need to list lib: ['ES2020', 'DOM'] so TypeScript knows fetch and Promise are available.

{
  "compilerOptions": {
    // --- LANGUAGE & ENVIRONMENT ---

    // Emit JavaScript compatible with Node 18 / modern browsers.
    // TypeScript will downcompile features not available in ES2022.
    "target": "ES2022",

    // Tell TypeScript which global APIs exist in this environment.
    // DOM gives you fetch, document, etc. ES2022 gives you Array.at(), etc.
    "lib": ["ES2022", "DOM"],

    // How import/export is compiled. Use 'commonjs' for Node, 'ESNext' for bundlers.
    "module": "commonjs",

    // Where to look when resolving modules.
    // 'node16' is the safest choice for modern Node.js projects.
    "moduleResolution": "node16",

    // --- STRICTNESS (always enable this in new projects) ---

    // Umbrella flag that enables 8 separate strict checks in one line.
    // Turning this off is how 'any' type sneaks back into your codebase.
    "strict": true,

    // Catch uses of variables that may be undefined after a loop or condition.
    // Saves you from subtle bugs TypeScript's strict mode doesn't catch by default.
    "noUncheckedIndexedAccess": true,

    // Error if a local variable is declared but never read.
    // Forces clean code — no 'import React' leftover cruft.
    "noUnusedLocals": true,

    // Error if a function parameter is declared but never used.
    // Prefix with _ (e.g. _unusedParam) to intentionally skip this check.
    "noUnusedParameters": true,

    // --- OUTPUT ---

    // Where compiled .js files land. Keep them out of your src directory.
    "outDir": "./dist",

    // The root of your source files — helps TypeScript mirror the folder structure.
    "rootDir": "./src",

    // Generate .d.ts declaration files so other TypeScript projects can consume this.
    "declaration": true,

    // Generate .js.map files so debuggers show original .ts source, not compiled JS.
    "sourceMap": true,

    // --- INTEROP ---

    // Allows: import express from 'express' instead of: import * as express from 'express'
    // Required for most npm packages that use CommonJS default exports.
    "esModuleInterop": true,

    // Skip type-checking of .d.ts files inside node_modules.
    // Dramatically speeds up compilation and avoids third-party declaration bugs.
    "skipLibCheck": true,

    // Throw an error if you import './MyComponent' but the file is './mycomponent'.
    // Prevents bugs on case-sensitive Linux filesystems when devs use macOS.
    "forceConsistentCasingInFileNames": true
  },

  // Include everything inside src. TypeScript walks subdirectories automatically.
  "include": ["src/**/*"],

  // Exclude compiled output and dependencies — never type-check these.
  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
}

Path Aliases and Project References — Escaping the '../../../' Nightmare

Once your project grows past about 20 files, relative imports become painful. You end up with lines like import { formatDate } from '../../../shared/utils/dateHelpers'. Change the file's location and everything breaks. Path aliases fix this.

Path aliases let you write import { formatDate } from '@utils/dateHelpers' from anywhere in the project. TypeScript resolves this at compile time using the paths option in tsconfig. But here's the catch everyone hits: TypeScript only handles the type resolution. The actual runtime resolution is still handled by Node.js or your bundler, so you need a companion tool (like tsconfig-paths for Node or your bundler's alias config for Webpack/Vite) to make it work at runtime too.

Project references solve a different problem: monorepos. If you have a shared packages/utils library and two apps (packages/api and packages/web) that both depend on it, you want each package to have its own tsconfig and to build independently. Project references let TypeScript understand the dependency graph between them, so it builds utils first and uses its compiled output when building api and web.

This also unlocks tsc --build (or tsc -b), which only recompiles packages whose source has actually changed — a massive speed win in large monorepos.

// ─── ROOT tsconfig.json (project with path aliases) ───────────────────────
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "moduleResolution": "node16",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "sourceMap": true,

    // baseUrl is required when using paths.
    // It anchors the path alias resolution to this directory.
    "baseUrl": ".",

    // Map the @alias/* pattern to a real folder path.
    // The array allows fallback paths (TypeScript tries them in order).
    "paths": {
      "@utils/*": ["src/shared/utils/*"],
      "@models/*": ["src/domain/models/*"],
      "@config/*": ["src/config/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Extending Configs and Environment-Specific Overrides — DRY tsconfig in the Real World

Most real projects need more than one tsconfig. You might want one for your main build, one for tests (which need different globals and can be more relaxed), and one for a strict CI check. Duplicating options across three files is a maintenance trap.

The extends key solves this. You define a base config with all shared options, then each environment-specific config extends it and adds only what's different. TypeScript deep-merges the two files, with the child config winning on any clash.

The community maintains @tsconfig/recommended and environment-specific presets like @tsconfig/node20 and @tsconfig/strictest on npm. These are great starting points — install one, extend it, and only add project-specific overrides. You get battle-tested defaults without memorising every flag.

A critical detail about extends and paths: include, exclude, and files arrays are not merged — they are entirely replaced by the child config. Only compilerOptions are merged. So if your base tsconfig has exclude: ['node_modules'] and your child config sets exclude: ['dist'], your child is now including node_modules — because it overwrote, not extended, the array. Always re-state exclusions in child configs.

// ─── tsconfig.base.json ───────────────────────────────────────────────────
// Shared foundation. All project configs extend this.
// Never used directly — only as a base.
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "moduleResolution": "node16",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "sourceMap": true
  }
}

// ─── tsconfig.json (production build) ─────────────────────────────────────
// Extends base and adds output configuration.
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
    // In production, unused variables are a hard error.
    "noUnusedLocals": true,
    "noUnusedParameters": true
  },
  "include": ["src/**/*"],
  // IMPORTANT: Re-declare exclude — it does NOT inherit from base.
  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
}

// ─── tsconfig.test.json (Jest / Vitest test runs) ─────────────────────────
// Extends base but relaxes rules that make test files painful.
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    // Tests don't emit — the test runner handles execution.
    "noEmit": true,
    // Tests legitimately have unused params in mock callbacks — relax this.
    "noUnusedParameters": false,
    // Add Jest's global types (describe, it, expect) without importing them.
    "types": ["jest", "node"]
  },
  // Include both source and test files so TypeScript understands imports in tests.
  "include": ["src/**/*", "tests/**/*"],
  "exclude": ["node_modules", "dist"]
}

// ─── Use in package.json scripts ──────────────────────────────────────────
// {
//   "scripts": {
//     "build":      "tsc -p tsconfig.json",
//     "type-check": "tsc -p tsconfig.json --noEmit",
//     "test":       "jest --project tsconfig.test.json"
//   }
// }

Project References and Composite Builds: Scaling TypeScript Across a Monorepo

When your repository grows beyond 50k lines, full tsc runs start to hurt. Even with skipLibCheck, waiting 40 seconds for a type-check after changing one file kills developer flow. Project references solve this by splitting your code into independently compilable units with explicit dependency graphs.

composite: true is the flag that makes a project reference-able. It tells TypeScript to generate .d.ts declaration files and a tsconfig.tsbuildinfo file for incremental builds. Without composite, a project cannot be referenced by another.

references in the root tsconfig lists the sub-projects. When you run tsc --build, TypeScript uses the declared dependency order to build them in the correct sequence. It also uses the .tsbuildinfo files to skip unchanged projects — a huge speed gain.

The catch: referenced projects must have composite: true, and the root project's outDir must be distinct from each sub-project's output. If they overlap, TypeScript will overwrite files and you'll get bizarre import errors.

Also note: tsc --build is strict about the rootDir and include patterns. Each referenced project must have its own rootDir that doesn't overlap with others. You can't just include everything from a shared src folder.

// ─── Root tsconfig.json ───────────────────────────────────────────────────
// This file acts as the orchestrator. It doesn't compile anything itself.
// It references sub-projects and tells TypeScript how to build them.
{
  "compilerOptions": {
    // composite is not required at root if it's not a library itself
    "target": "ES2022",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "references": [
    { "path": "./packages/utils" },
    { "path": "./packages/api" },
    { "path": "./packages/web" }
  ]
}

// ─── packages/utils/tsconfig.json ─────────────────────────────────────────
{
  "compilerOptions": {
    "composite": true,  // Required to be reference-able
    "target": "ES2022",
    "module": "commonjs",
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,  // mandatory for composite
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

// ─── packages/api/tsconfig.json ───────────────────────────────────────────
{
  "compilerOptions": {
    "composite": true,
    "target": "ES2022",
    "module": "commonjs",
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "sourceMap": true
  },
  "references": [
    // API depends on utils
    { "path": "./../utils" }
  ],
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

// ─── Build command ───────────────────────────────────────────────────────-
// $ npx tsc --build packages/api/tsconfig.json
// This builds utils first (if needed), then api.
// --dry shows what would be built without actually building.
// --clean removes all build artifacts.

The `files`, `include`, and `exclude` Trio — Stop Compiling Everything in Sight

Most devs let tsc scan the whole project. That’s lazy. Your tsconfig.json’s files, include, and exclude fields exist to tell TypeScript exactly what to compile — and more importantly, what to ignore. files is for single-file entry points (rare). include is your workhorse: glob patterns like src/*/.ts. exclude kills noise: node_modules, dist, test fixtures. Without these, TypeScript loads every .ts file in your repo, including dead code and generated output. That slows down editor intellisense and bloats compilation times in CI. The real pro move: start with a tight include and only widen it when you must. Your tsconfig.json isn’t a suggestion — it’s a contract with the compiler.

{
  "compilerOptions": { ... },
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/__mocks__/*"]
}

The `outDir`/`rootDir` Symmetry — Why Your Build Output Looks Like a Mess

Ever run tsc and get a mirror of your src/ folder inside dist/ but with a nested src/ subfolder? That’s rootDir missing. rootDir tells TypeScript the root of your source tree. outDir is where compiled output lands. Without setting rootDir explicitly, TypeScript infers the longest common path of all input files — and that often points to your project root, not src/. The fix: set rootDir: "./src" and outDir: "./dist". Now src/app.ts compiles to dist/app.js, not dist/src/app.js. This matters for runtime imports, debugging source maps, and Docker layer caching. Don’t guess. Set both. Explicitly.

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"]
}