Skip to content

The tsconfig.json Configuration

Configure the TypeScript compiler with tsconfig.json: target, strict, paths, and more.

What you'll learn

  • The essential tsconfig.json options: target, module, and lib
  • How strict mode enables a bundle of safety checks
  • Path aliases with baseUrl and paths for cleaner imports
  • Project references and composite projects for monorepos

Concept

Core Options

The tsconfig.json file configures the TypeScript compiler. The most important options are target (the JavaScript version to compile to, e.g. es2020), module (the module system, e.g. esnext or commonjs), and lib (which built-in APIs are available, e.g. ["es2020", "dom"]). outDir specifies where compiled JavaScript goes, and rootDir specifies where source files live.

Strict Mode

The strict: true flag enables a bundle of safety checks: strictNullChecks (null/undefined are not assignable to other types), noImplicitAny (parameters must have types or be inferable), strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, noImplicitThis, and alwaysStrict. Enabling strict is the single best decision for a new TypeScript project — it catches the most bugs with the least effort.

Path Aliases and References

Path aliases (paths) let you import with absolute paths instead of long relative ones: import { User } from "@models/user" instead of ../../../models/user. You configure them with baseUrl and paths in tsconfig. Project references (references with composite: true) let you split a large project into smaller sub-projects that compile independently, which is essential for monorepo performance.

Example

              // tsconfig.json — a modern, strict configuration.
{
  "compilerOptions": {
    "target": "es2020",
    "module": "esnext",
    "moduleResolution": "bundler",
    "lib": ["es2020", "dom"],

    // Strict mode — enables all safety checks.
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,

    // Output.
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "sourceMap": true,

    // Path aliases for clean imports.
    "baseUrl": "./src",
    "paths": {
      "@models/*": ["models/*"],
      "@utils/*": ["utils/*"],
      "@components/*": ["components/*"]
    },

    // Module resolution.
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
            

tsconfig.json controls the compiler. target sets the JS version, strict enables safety checks, paths creates import aliases. Always enable strict for new projects — it catches the most bugs.

Try it

  • Code Minifier

    The target setting determines which JS features get transpiled down.

  • Code Diff

    Compare compiled output across different target settings.

Common mistakes

The mistake

Disabling strictNullChecks or strict to avoid fixing type errors

The fix

Keep strict enabled. The errors it surfaces are real bugs. Fix the code rather than weakening the compiler. The short-term pain prevents long-term runtime errors.

The mistake

Setting target too low and losing modern JavaScript features

The fix

Set target to match your runtime environment (es2020 for modern browsers/Node). A too-low target transpiles features unnecessarily, producing larger and slower output.

Practice The tsconfig.json Configuration

1 exercise

Practice The tsconfig.json Configuration

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors