Configuration and Best Practices

A well-configured TypeScript project is easier to maintain, produces fewer bugs, and provides a better developer experience. This lesson covers the tsconfig.json file in depth, recommended compiler options, linting with ESLint, declaration files, and strategies for migrating JavaScript projects to TypeScript.

---

tsconfig.json

The tsconfig.json file is the heart of every TypeScript project. It tells the compiler which files to include, what JavaScript version to target, and how strictly to check your code.

Generate a starter config with:

// npx tsc --init

Key Compiler Options

strict

The strict flag enables a family of strict type-checking options:

// tsconfig.json
// {
//   "compilerOptions": {
//     "strict": true
//   }
// }

This enables:

• strictNullChecks — null and undefined are not assignable to other types
• strictFunctionTypes — function parameter types are checked contravariantly
• strictBindCallApply — bind, call, and apply are strictly checked
• strictPropertyInitialisation — class properties must be initialised
• noImplicitAny — expressions and declarations with an implied any type cause errors
• noImplicitThis — this expressions with an implied any type cause errors
• alwaysStrict — emits "use strict" in every file
• useUnknownInCatchVariables — catch variables are typed as unknown

Always use strict: true for new projects. It catches the most bugs and represents best practice.

target

Specifies the ECMAScript version for the emitted JavaScript:

// "target": "ES2020" — modern browsers and Node 14+
// "target": "ES2022" — top-level await, class fields
// "target": "ESNext"  — latest features

Choose the lowest target that your runtime environment supports.

module

Specifies the module system for the emitted JavaScript:

// "module": "ESNext"       — ES modules (recommended for bundlers)
// "module": "CommonJS"     — require/module.exports (Node.js legacy)
// "module": "NodeNext"     — Node.js native ESM support

moduleResolution

Controls how TypeScript resolves module import paths:

// "moduleResolution": "bundler" — for Vite, webpack, etc.
// "moduleResolution": "node"    — classic Node.js resolution
// "moduleResolution": "nodenext" — Node.js ESM resolution

---

Recommended tsconfig.json

Here is a recommended configuration for a modern TypeScript project: