TypeScript tsconfig and Tooling

tsconfig.json patterns, diagnostics, and project references.

View
StandardDetailedCompact
Export
Copy the compact sheet, download it, or print it.
Download
`D` dense toggle · `C` copy all

tsconfig Basics

Compiler options that shape emitted JS and type-checking behavior.

Minimal tsconfig

A small strict config for many projects.

jsonANYtypescripttsconfigstrict
json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true
  }
}

A `tsconfig.json` marks the project root and controls compilation behavior.

Node-focused tsconfig

Example config for modern Node.js projects.

jsonANYtypescripttsconfignode
json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}

NodeNext settings are common when using native ESM in Node.

Configure path aliases

Use `baseUrl` and `paths` for ergonomic imports.

jsonANYtypescripttsconfigpaths
json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

`paths` is useful for app code, but make sure your bundler or runtime understands the aliases too.

Enable strict mode

Turn on TypeScript’s strict family checks.

jsonANYtypescripttsconfigstrict
json
{
  "compilerOptions": {
    "strict": true
  }
}

The TSConfig reference documents `strict` as a top-level switch for stronger type checking.

Control included files

Use `include` and `exclude` patterns.

jsonANYtypescripttsconfigincludeexclude
json
{
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["dist", "node_modules"]
}

File inclusion bugs are common, so keep these patterns simple and explicit.

Compiler Diagnostics and Debugging

Commands and flags that explain TypeScript behavior.

List compilation files

Print files included in the program.

bashANYtypescripttscdiagnostics
bash
npx tsc --listFiles

Useful when a file is unexpectedly missing or included.

Extended diagnostics

Measure compiler performance details.

bashANYtypescripttscperformance
bash
npx tsc --extendedDiagnostics

Helpful in large projects when TypeScript builds feel slow.

Show resolved config

Print the final config after `extends` resolution.

bashANYtypescripttsctsconfigdebugging
bash
npx tsc --showConfig

Useful when debugging inherited configs and unexpected compiler options.

Clean build artifacts

Remove `.tsbuildinfo` and build outputs before recompiling.

bashANYtypescriptbuildincremental
bash
rm -rf dist *.tsbuildinfo && npx tsc --build

A clean rebuild can help when incremental caches get out of sync.

Project References

Split larger repos into buildable TypeScript projects.

Composite project config

Enable settings required for project references.

jsonANYtypescriptproject-referencescomposite
json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "dist"
  }
}

Composite projects are required when you want to use `tsc --build` with references.

Reference another project

Declare a dependency on a sibling TS project.

jsonANYtypescriptproject-references
json
{
  "references": [
    { "path": "../shared" }
  ]
}

Project references help large monorepos build incrementally and in dependency order.

Clean project reference outputs

Use build mode clean command.

bashANYtypescriptproject-referencesbuild
bash
npx tsc --build --clean

Useful when resetting build-mode artifacts across a multi-project repo.

Recommended next

No recommendations yet.