Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 96 ยท Getting Started

The tsconfig.json File

Understand tsconfig.json - strict, target, module, lib, outDir, noEmit, noUncheckedIndexedAccess, verbatimModuleSyntax and more - with recommended modern configs.

Every TypeScript project has a tsconfig.json file in its root folder. It tells the compiler which files belong to the project and how to treat them: how strict to be, which JavaScript version to produce, which built-in APIs exist and where to write the output. When you run tsc with no arguments, or open the folder in VS Code, this file is what the tools read.

There are well over a hundred compiler options, but a modern project only needs a dozen or so. In this lesson you'll learn what the essential ones do, see several of them in action in runnable examples, and get three recommended configurations you can copy: one for Node.js, one for front-end apps built with a bundler, and one for libraries.

The shape of the file

A tsconfig.json is JSON with two small extras: comments and trailing commas are allowed. Here is a small but complete example:

JSON
{
  // Settings for the compiler
  "compilerOptions": {
    "target": "es2024",
    "module": "nodenext",
    "strict": true,
    "outDir": "dist",
    "rootDir": "src",
    "skipLibCheck": true
  },
  // Which files belong to the project
  "include": ["src"],
  "exclude": ["src/**/*.test.ts"]
}

The top-level keys you'll use most are:

Key Purpose
compilerOptions All the settings that change how code is checked and emitted.
include Files or folders that belong to the project (globs such as src/**/* are allowed).
exclude Paths to leave out of include. node_modules and outDir are skipped automatically.
files An explicit list of single files, for very small projects.
extends Another config file (or an npm package) whose settings this one starts from.
references Other TypeScript projects this one depends on, for large multi-package repositories.

You create the file with npx tsc --init, which writes a commented starter config. Two commands help when you're unsure what's going on:

Terminal
npx tsc --showConfig      # print the final config after extends and defaults
npx tsc -p tsconfig.build.json   # use a different config file

Type-checking options

strict

"strict": true turns on a whole family of checks at once, including strictNullChecks (values that might be null or undefined must be checked) and noImplicitAny (every value must have a known type). Every new project should use it. Since TypeScript 6.0, strict is true by default (earlier versions defaulted to false), but write it explicitly anyway, so the file states your intent and the project still behaves the same in older tools. TypeScript 6.0 changed a few other defaults too: module is now esnext, target is the newest supported ECMAScript version (currently es2025), and types is an empty list, so global type packages such as @types/node must be listed in types to be loaded. Our editors always run in strict mode. The next lesson, Strict Mode Explained, demonstrates each flag in the family.

noUncheckedIndexedAccess

This option is not part of strict, but many teams turn it on. Without it, TypeScript assumes that reading an array element or an object key always finds something. Our editors leave it off, which means you can see exactly the bug it prevents:

TypeScript An index that is out of range

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

The program type-checks, prints undefined, then crashes with TypeError: Cannot read properties of undefined (reading 'toUpperCase') on line 5. TypeScript typed third as string, but there is no third color. With noUncheckedIndexedAccess, colors[2] has the type string | undefined, and the compiler would insist on a check first ('third' is possibly 'undefined'). The cost is a few extra checks in loops over indexes; the benefit is that a whole class of crashes is gone. Index Signatures and Record shows how to work with it comfortably.

exactOptionalPropertyTypes

Also outside strict and off in our editors. Normally, an optional property nickname?: string accepts the value undefined written out explicitly, which is subtly different from leaving it out:

TypeScript Missing versus explicitly undefined

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

It prints false { name: 'Lin' } and then true { name: 'Ada', nickname: undefined }. The two objects behave differently with in, Object.keys and spreading, yet both are accepted. With exactOptionalPropertyTypes, nickname?: string means "either absent or a string", and the second object becomes an error unless you write nickname?: string | undefined. It's strict and occasionally inconvenient, so teams enable it deliberately rather than by habit.

Other useful checks

Option What it reports
noImplicitReturns A function where some paths return a value and others don't
noFallthroughCasesInSwitch A case that falls into the next one without break or return
noImplicitOverride Class methods that override a parent method without the override keyword (Inheritance)
noUnusedLocals, noUnusedParameters Unused variables and parameters (many teams leave this to a linter instead)
noPropertyAccessFromIndexSignature Using obj.key instead of obj['key'] for keys that come from an index signature

Output options

target

target sets the JavaScript version the compiler emits, such as es2022 or es2024. Newer syntax is rewritten when the target is older, as you saw in How TypeScript Works. All browsers and Node.js versions in support today handle at least ES2022, so pick a recent target. es5 and es3 are no longer available in TypeScript 7.

lib

lib lists the built-in type definitions the checker loads: which global objects and methods exist. If you don't set it, it follows target and includes the browser DOM. Our editors use esnext only, so they know the newest JavaScript built-ins but nothing about web pages:

TypeScript What lib esnext provides

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

All three are recent additions to JavaScript (toSorted in ES2023, Object.groupBy in ES2024, Set.prototype.union in ES2025), and the checker accepts them because they're in the esnext lib. The output ends with Set(4) { 2, 4, 6, 8 }.

Now the DOM. Because lib doesn't include dom, the global document doesn't exist as far as the checker knows:

TypeScript No DOM in our editors (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

The compiler answers with a helpful hint:

TEXT
main.ts(1,17): error TS2584: Cannot find name 'document'. Do you need to change your target library? Try changing the 'lib' compiler option to include 'dom'.

A browser project would set "lib": ["es2024", "dom"]. Remember that lib only describes what exists; it doesn't add anything at runtime. Claiming esnext while targeting an old browser lets you call methods that aren't there.

types

Packages under node_modules/@types add global type declarations, such as the process object and node: modules from @types/node. The types option chooses which of them are loaded. Listing them explicitly ("types": ["node"]) keeps stray global types out of your project and speeds up checking. Our editors load the Node.js types.

outDir, rootDir and noEmit

  • outDir is where emitted .js files go, for example dist.
  • rootDir is the folder whose structure is mirrored into outDir: src/util/math.ts becomes dist/util/math.js.
  • noEmit makes tsc a pure type-checker that writes nothing. Use it when Vite, esbuild or Node.js type stripping runs your code.
  • declaration writes .d.ts type files next to the JavaScript, which libraries need (Declaration Files).
  • sourceMap writes .js.map files, so stack traces and debuggers point at your .ts lines. Our editors use it, which is why runtime errors show main.ts line numbers.
  • noEmitOnError skips emitting when there are type errors. Our editors use it too.

Module options

module and moduleResolution

module decides which module system the emitted code uses and which import rules the checker enforces. moduleResolution decides how an import path like './math' or 'lodash' is turned into a file. In modern projects you pick one of two pairs:

Your code runs in... module moduleResolution
Node.js directly (tsc output or type stripping) nodenext nodenext (the default for this module setting)
A bundler such as Vite, webpack or esbuild preserve or esnext bundler

With nodenext, TypeScript follows Node.js's real rules exactly: a package.json with "type": "module" makes .ts files ES modules, and relative imports need a file extension. With bundler, extensions are optional, like in most front-end tooling. The old node10 resolution mode was removed in TypeScript 7. Modules covers the details.

Our editors use nodenext, and the editor file is an ES module, so import from Node.js built-ins and top-level await both work:

TypeScript An ES module with top-level await

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

It prints waited 50 ms, report.ts .ts and true.

verbatimModuleSyntax, isolatedModules and erasableSyntaxOnly

These three options keep your code safe for tools that compile one file at a time (Vite, esbuild, swc, Node.js type stripping):

  • verbatimModuleSyntax makes TypeScript keep every import and export exactly as written, unless it's marked type-only. You must write import type { User } from './user' (or import { type User }) for imports used only as types. The result is predictable output with no guessing about which imports to remove.
  • isolatedModules reports code that can't be compiled without looking at other files. verbatimModuleSyntax already implies most of it.
  • erasableSyntaxOnly (TypeScript 5.8+) reports features that generate code, such as enum, namespaces with values and constructor parameter properties. Turn it on when Node.js type stripping runs your files, so that tsc and Node.js agree on what's allowed.

Other common options

Option Use
skipLibCheck Don't type-check .d.ts files from dependencies. Faster, and avoids errors in other people's types. Almost always true.
allowImportingTsExtensions Allow import './math.ts' (only with noEmit or declaration-only output). Pairs with Node.js type stripping.
rewriteRelativeImportExtensions Turn ./math.ts into ./math.js in the output (TypeScript 5.7+).
resolveJsonModule Allow import data from './data.json' with { type: 'json' } with typed contents.
jsx How .tsx files are compiled, e.g. react-jsx (TypeScript with React).
allowJs, checkJs Include and check .js files (Migrating JavaScript to TypeScript).
moduleDetection: "force" Treat every file as a module, even without import or export.

A Node.js app run with type stripping

Node.js runs the .ts files itself, and tsc only checks:

JSON
{
  "compilerOptions": {
    "target": "es2024",
    "module": "nodenext",
    "types": ["node"],
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true,
    "allowImportingTsExtensions": true,
    "noEmit": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Run it with node src/main.ts and check it with npx tsc. If you'd rather compile to JavaScript first, drop noEmit and allowImportingTsExtensions, add "outDir": "dist", "rootDir": "src" and "sourceMap": true, and run node dist/main.js.

A front-end app with a bundler

The bundler produces the JavaScript; tsc only checks:

JSON
{
  "compilerOptions": {
    "target": "es2022",
    "lib": ["es2024", "dom"],
    "module": "preserve",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Framework starters (Vite, Next.js, Angular and others) generate a config like this for you, often split across a few files with extends.

A library published to npm

Libraries emit JavaScript and type declarations, so users get types:

JSON
{
  "compilerOptions": {
    "target": "es2022",
    "module": "nodenext",
    "strict": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "rootDir": "src",
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Tooling: Linting, Testing and Building covers the package.json side (exports, types).

Sharing settings with extends

extends loads another config first, and your file then overrides individual options. The community-maintained @tsconfig/* packages on npm provide ready-made bases, for example for specific Node.js versions or a "strictest" set:

JSON
{
  "extends": "@tsconfig/strictest/tsconfig.json",
  "compilerOptions": {
    "outDir": "dist"
  },
  "include": ["src"]
}

Paths in include, exclude and outDir are always resolved relative to the file they're written in.

What our editors use

The editors in this course can't load a tsconfig.json; they always use the same fixed settings, equivalent to:

JSON
{
  "compilerOptions": {
    "strict": true,
    "target": "es2024",
    "lib": ["esnext"],
    "module": "nodenext",
    "types": ["node"],
    "noEmitOnError": true,
    "sourceMap": true
  }
}

In practice that means: strict mode, modern JavaScript built-ins, Node.js APIs, ES modules with top-level await, no DOM, and no noUncheckedIndexedAccess or exactOptionalPropertyTypes. Lessons that depend on those last two options explain what would change.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Your project uses Vite to build and serve the code. Which option should the tsconfig.json usually include?

    Bundlers strip types themselves, so tsc is used purely as a type-checker with noEmit. es3 and node10-era settings are gone in modern TypeScript.
  2. 2. With our editor's settings, does const xs = [1, 2]; const n: number = xs[5]; compile?

    Without noUncheckedIndexedAccess, element access is assumed to succeed and has type number. At runtime n would be undefined.
  3. 3. What does the lib option change?

    lib only loads type definitions for globals. It doesn't add code at runtime; target controls the output syntax.
  4. 4. Which option makes tsc report an enum so that the file can run with Node.js type stripping?

    erasableSyntaxOnly (TypeScript 5.8+) flags syntax that needs generated JavaScript, such as enums, value namespaces and parameter properties.
  5. 5. With exactOptionalPropertyTypes on, which assignment to { nickname?: string } is an error?

    The option makes an optional property mean "absent or a string". Writing undefined explicitly requires the type string | undefined.

Summary

  • tsconfig.json defines a project: compilerOptions, include/exclude, and optionally extends and references. Create one with npx tsc --init; inspect the result with tsc --showConfig.
  • Always set "strict": true. Consider noUncheckedIndexedAccess (indexes may be undefined) and exactOptionalPropertyTypes (optional means absent).
  • target sets the output syntax version; lib sets which built-in APIs exist; types selects global @types packages.
  • outDir, rootDir, declaration and sourceMap shape the output; noEmit turns tsc into a pure checker.
  • Use module/moduleResolution nodenext for Node.js and preserve/bundler for bundlers.
  • verbatimModuleSyntax, isolatedModules and erasableSyntaxOnly keep code safe for single-file tools like Vite and Node.js type stripping.
  • Our editors use strict mode, target es2024, lib esnext (no DOM), module nodenext and Node.js types.

Next: Strict Mode Explained โ€” every flag in the strict family and the bug each one catches.