tsconfig.json Explained: Options, Defaults and Examples

tsconfig.json is the configuration file of a TypeScript project. When you run tsc with no arguments, the compiler looks for it in the current folder (then in parent folders), reads the options in compilerOptions, and checks the files listed by include. A small but complete one:

{
    "compilerOptions": {
        "target": "es2022",
        "module": "nodenext",
        "strict": true,
        "rootDir": "./src",
        "outDir": "./dist"
    },
    "include": ["src"]
}

This compiles every TypeScript file in src into JavaScript in dist, as ES2022 code, using Node.js's module rules, with all strict checks on. npx tsc --init generates a longer starting file with a comment on every option.

The file is JSON with comments: // comments, /* */ comments and trailing commas are all accepted.

A Recommended Starting Config

For a Node.js application or script:

{
    "compilerOptions": {
        "rootDir": "./src",
        "outDir": "./dist",

        "target": "es2024",
        "lib": ["es2024"],
        "module": "nodenext",
        "types": ["node"],

        "strict": true,
        "noUncheckedIndexedAccess": true,
        "verbatimModuleSyntax": true,
        "skipLibCheck": true,
        "sourceMap": true
    },
    "include": ["src"]
}

It needs npm install --save-dev @types/node for the Node.js types. With module: "nodenext", the "type" field in package.json decides whether a .ts file is an ES module ("type": "module") or CommonJS ("type": "commonjs", which npm init -y writes). Use "type": "module" for new projects that use import and export.

For code that a bundler such as Vite, esbuild or webpack builds, the bundler writes the JavaScript and tsc only checks:

{
    "compilerOptions": {
        "target": "es2022",
        "lib": ["es2022", "dom"],
        "module": "preserve",
        "noEmit": true,

        "strict": true,
        "noUncheckedIndexedAccess": true,
        "verbatimModuleSyntax": true,
        "isolatedModules": true,
        "skipLibCheck": true,
        "jsx": "react-jsx"
    },
    "include": ["src"]
}

Framework starters (Vite, Next.js, Angular) generate their own tsconfig.json. Start from theirs rather than replacing it.

The Options That Matter

target and lib

target says which JavaScript version the output must run on. Syntax newer than the target is rewritten: with "target": "es2017", a class field or ??= is turned into older code. The lowest target TypeScript 7 accepts is es2015 (es6); es5 was removed.

target does not add missing runtime APIs. That is lib's job to describe and a polyfill's job to supply. lib tells the checker which built-in objects and methods exist. Its default follows target and also includes the browser DOM types, so document type-checks even in a Node.js project unless you set lib yourself. Using a method from a newer standard than your lib is a compile error:

src/b.ts(1,24): error TS2550: Property 'toSorted' does not exist on type 'number[]'. Do you need to change your target library? Try changing the 'lib' compiler option to 'es2023' or later.

The runnable examples in these docs use the es2022 lib, so toSorted, Object.groupBy and the new Set methods are not available in them.

module and moduleResolution

module has three sensible values for new code:

• nodenext: for code Node.js runs. Each file is ESM or CommonJS according to its extension (.mts, .cts) or the nearest package.json "type", exactly as Node decides. Relative imports in ES modules need a file extension, written as .js even though the source is .ts: import { add } from "./math.js". moduleResolution follows automatically.
• preserve: for code a bundler processes. Imports are left as written, and resolution uses the bundler rules, which allow extensionless imports.
• esnext: plain ES module output, with bundler resolution. It is the default when module is not set.

A common first error with the tsc --init config comes from npm init -y writing "type": "commonjs":

src/main.ts(1,10): error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'.

The file uses import, but package.json says the project is CommonJS. Change "type" to "module". The modules page covers imports and exports in detail.

strict and the Checking Options

"strict": true turns on a group of checks at once: noImplicitAny, strictNullChecks, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, strictBuiltinIteratorReturn, noImplicitThis and useUnknownInCatchVariables. It is the default in TypeScript 7 and on in every runnable example here. Code written for strict mode narrows before it uses a value that may be missing:

function initials(fullName: string | undefined): string {
    if (fullName === undefined) {
        return "?";
    }
    return fullName
        .split(" ")
        .map((part) => part[0])
        .join("");
}

console.log(initials("Ada Lovelace")); // AL
console.log(initials(undefined));      // ?

Without an annotation, a parameter's type cannot be inferred, and noImplicitAny reports it:

// This does not compile: noImplicitAny is part of strict.
function double(n) {
    return n * 2;
}

console.log(double(21));

index.ts(2,17): error TS7006: Parameter 'n' implicitly has an 'any' type.

strict does not include every useful check. Two worth adding are noUncheckedIndexedAccess (an array element or index-signature lookup has type T | undefined) and exactOptionalPropertyTypes (an optional property cannot be explicitly set to undefined); tsc --init turns both on. Style checks such as noUnusedLocals, noImplicitReturns and noFallthroughCasesInSwitch are off by default.

Which Files: include, exclude, rootDir, outDir

Without include or files, the project contains every .ts, .tsx and .d.ts file in the folder and its subfolders. node_modules is always left out. The outDir is left out too, but only while you have not set exclude: a custom exclude list replaces that default, so add the output folder to it. include and exclude take glob patterns:

{
    "include": ["src", "scripts/**/*.ts"],
    "exclude": ["src/**/*.test.ts"]
}

exclude only filters what include found. A file that another included file imports is still compiled.

outDir is where output goes, and rootDir is the part of the source tree that is mirrored into it: with "rootDir": "./src", src/api/users.ts becomes dist/api/users.js. Set both. rootDir defaults to the folder that holds tsconfig.json, so if you set only outDir while the sources sit in src, TypeScript 7 stops with:

error TS5011: The common source directory of 'tsconfig.json' is './src'. The 'rootDir' setting must be explicitly set to this or another path to adjust your output's file layout.

Output Options: noEmit, declaration, sourceMap

• "noEmit": true makes tsc a pure type checker. Use it when another tool (a bundler, tsx, Node.js type stripping) produces the JavaScript.
• "declaration": true writes a .d.ts file per module, the types without the code. Libraries need it so their users get types. declarationMap adds maps for "go to definition" into the .ts source.
• "sourceMap": true writes .js.map files so debuggers and stack traces point at the .ts lines.
• "noEmitOnError": true writes nothing while there are type errors. Without it, tsc reports the errors and still writes the JavaScript.

types, esModuleInterop and skipLibCheck

types lists the @types packages that are loaded globally, without an import. TypeScript 7's default is an empty list, so after npm install --save-dev @types/node you also add "types": ["node"]; otherwise process and require stay unknown (error TS2591: Cannot find name 'process'). Test runners with global functions, such as Jest's describe, go in the same list.

esModuleInterop makes default imports of CommonJS packages work (import express from "express"). It is always on in TypeScript 7, and setting it to false is an error.

skipLibCheck skips type-checking declaration files. It speeds up builds and avoids errors inside node_modules that you cannot fix, at the cost of not noticing conflicts between two libraries' types. Most projects turn it on.

Sharing Settings with extends

extends loads another config and lets this file override parts of it:

{
    "extends": "./tsconfig.base.json",
    "compilerOptions": {
        "rootDir": "./src",
        "outDir": "./dist"
    },
    "include": ["src"]
}

compilerOptions are merged option by option, while include, exclude and files from the base are replaced, not merged, if this file sets them. Paths in the base file are resolved relative to the base file. extends also accepts a package: the @tsconfig/bases project publishes one per environment, for example npm install --save-dev @tsconfig/node24 and then "extends": "@tsconfig/node24/tsconfig.json".

To see the final settings after all extends and defaults are applied, run:

npx tsc --showConfig

Options Removed in TypeScript 7

TypeScript 6 deprecated these settings and TypeScript 7 removed them. A config that still uses one fails with error TS5108 or TS5102, for example Option 'baseUrl' has been removed. Please remove it from your configuration.

The TypeScript 7 page lists the other changes in that release, including the new defaults this table does not cover.