TypeScript tsconfig Patterns Reference

TL;DR

• Bottom line: Start every project with strict: true, moduleResolution: "bundler" (or "nodenext"), target: "es2022", and skipLibCheck: true.
• Key tool/command: tsc --showConfig
• Watch out for: Setting paths aliases without configuring the same aliases in your bundler — TypeScript does NOT rewrite import paths.
• Works with: TypeScript 5.0–5.7, Node.js 18+, all major bundlers.

Constraints

• strict: true is non-negotiable for new projects
• moduleResolution must match your module setting — "bundler" for Vite/webpack, "nodenext" for pure Node.js
• Never set skipLibCheck: false in large projects — dramatically slows compilation
• target and lib are separate concerns — target controls emit, lib controls types
• paths aliases require bundler config too — TypeScript does NOT rewrite import paths

Quick Reference

Decision Tree

START
├── Pure Node.js (no bundler)?
│   ├── YES → module: "nodenext", moduleResolution: "nodenext"
│   └── NO ↓
├── Using Vite, webpack, esbuild?
│   ├── YES → module: "esnext", moduleResolution: "bundler", noEmit: true
│   └── NO ↓
├── Building npm library?
│   ├── YES → declaration: true, declarationMap: true, outDir: "./dist"
│   └── NO ↓
├── React project?
│   ├── YES → jsx: "react-jsx"
│   └── NO ↓
├── Monorepo?
│   ├── YES → composite: true, references: [...]
│   └── NO ↓
└── DEFAULT → strict: true, target: "es2022", skipLibCheck: true

Step-by-Step Guide

1. Initialize tsconfig.json

Generate a starter config. [src5]

npx tsc --init

Verify: ls tsconfig.json → file exists

2. Set base options

Essential options for every project. [src2]

{
  "compilerOptions": {
    "strict": true,
    "target": "es2022",
    "skipLibCheck": true,
    "esModuleInterop": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "noUncheckedIndexedAccess": true,
    "resolveJsonModule": true,
    "forceConsistentCasingInFileNames": true,
    "moduleDetection": "force"
  }
}

3. Configure module resolution

Choose based on bundler vs Node.js. [src4]

// For bundlers (Vite, webpack):
{ "module": "esnext", "moduleResolution": "bundler", "noEmit": true }

// For pure Node.js:
{ "module": "nodenext", "moduleResolution": "nodenext", "outDir": "./dist" }

Code Examples

Vite + React + TypeScript

{
  "compilerOptions": {
    "strict": true, "target": "es2022",
    "lib": ["es2022", "dom", "dom.iterable"],
    "module": "esnext", "moduleResolution": "bundler",
    "isolatedModules": true, "noEmit": true,
    "jsx": "react-jsx",
    "skipLibCheck": true, "noUncheckedIndexedAccess": true,
    "verbatimModuleSyntax": true,
    "baseUrl": ".", "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src", "vite-env.d.ts"]
}

Node.js + Express Backend

{
  "compilerOptions": {
    "strict": true, "target": "es2022", "lib": ["es2022"],
    "module": "nodenext", "moduleResolution": "nodenext",
    "outDir": "./dist", "rootDir": "./src",
    "sourceMap": true, "declaration": true, "incremental": true,
    "skipLibCheck": true, "noUncheckedIndexedAccess": true,
    "verbatimModuleSyntax": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

npm Library

{
  "compilerOptions": {
    "strict": true, "target": "es2022", "lib": ["es2022"],
    "module": "esnext", "moduleResolution": "bundler",
    "outDir": "./dist", "rootDir": "./src",
    "declaration": true, "declarationMap": true, "sourceMap": true,
    "skipLibCheck": true, "noUncheckedIndexedAccess": true,
    "isolatedModules": true, "verbatimModuleSyntax": true
  },
  "include": ["src/**/*"],
  "exclude": ["**/*.test.ts"]
}

Anti-Patterns

Wrong: Skipping strict mode

// ❌ BAD — silent any, null bugs everywhere
{ "compilerOptions": { "strict": false, "target": "es5" } }

Correct: Always enable strict

// ✅ GOOD — catches bugs at compile time
{ "compilerOptions": { "strict": true, "target": "es2022" } }

Wrong: Using "moduleResolution": "node" with a bundler

// ❌ BAD — "node" is legacy, misses package.json exports
{ "module": "esnext", "moduleResolution": "node" }

Correct: Use "bundler" with bundlers

// ✅ GOOD — supports exports, no extension requirement
{ "module": "esnext", "moduleResolution": "bundler" }

Common Pitfalls

• verbatimModuleSyntax breaks CJS: Fix: only use with ESM output or module: "nodenext". [src3]
• paths aliases not working at runtime: Fix: add vite-tsconfig-paths or tsconfig-paths. [src1]
• Stale tsbuildinfo: Fix: rm tsconfig.tsbuildinfo && npx tsc. [src6]
• Missing DOM types on server: Fix: "lib": ["es2022"] for Node.js. [src1]
• exactOptionalPropertyTypes too strict: Fix: start with strict: true alone. [src2]
• outDir/rootDir mismatch: Fix: rootDir = common ancestor of source files. [src5]

Diagnostic Commands

# Show fully resolved tsconfig
npx tsc --showConfig

# Type-check without emitting
npx tsc --noEmit

# List files that would be compiled
npx tsc --listFiles

# Check TypeScript version
npx tsc --version

# Build with verbose diagnostics
npx tsc --extendedDiagnostics

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• moduleResolution: "bundler" requires module: "esnext" or "preserve"
• verbatimModuleSyntax replaces older importsNotUsedAsValues
• TypeScript path aliases do NOT affect emitted JavaScript
• composite: true requires declaration: true and disallows noEmit: true