TypeScript Configuration

The One Flag That Found 200 Bugs

Monday morning code review. A senior developer suggested: "Let's enable strict mode."

I hesitated. Our codebase was 35,000 lines. Surely enabling strict mode would create thousands of errors we'd spend weeks fixing?

I created a branch and added one line to tsconfig.json:

{
  "compilerOptions": {
    "strict": true
  }
}

Ran tsc. Held my breath.

227 errors.

Not thousands. Just 227. And they were all real bugs:

// Before strict mode - compiled fine
function getUserName(user) {  // Implicit any
  return user.name.toUpperCase();  // Crashes if user is null!
}

// Error found by strict mode:
// ✗ Parameter 'user' implicitly has an 'any' type

// Before - compiled fine
class UserService {
  private apiKey;  // Implicit any
  
  constructor() {
    // Forgot to initialize apiKey!
  }
  
  fetchUser() {
    return fetch(`/api/users`, {
      headers: { 'X-API-Key': this.apiKey }  // undefined!
    });
  }
}

// Error found by strict mode:
// ✗ Property 'apiKey' has no initializer

We fixed all 227 errors in 3 days. Deployed to staging.

Result: Caught 14 production bugs before they happened. Null reference errors: gone. Implicit any footguns: eliminated.

That one flag – "strict": true – was the highest ROI config change we ever made.

This article covers tsconfig.json options that prevent bugs, improve code quality, and make TypeScript actually useful.

---

Basic tsconfig.json

Minimal configuration to get started.

Bare Minimum

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

What Each Option Does

• target: JavaScript version to output (ES5, ES2015, ES2020, ESNext)

• module: Module system (commonjs, es2015, esnext)

• outDir: Where compiled files go

• rootDir: Source code location

• include: Files to compile

• exclude: Files to ignore

---

Strict Mode Options

Enable all strict type-checking options at once.

strict: true (Recommended)

{
  "compilerOptions": {
    "strict": true
  }
}

Enables all of:

• noImplicitAny

• strictNullChecks

• strictFunctionTypes

• strictBindCallApply

• strictPropertyInitialization

• noImplicitThis

• alwaysStrict

Individual Strict Options

You can enable them individually:

{
  "compilerOptions": {
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictBindCallApply": true,
    "strictPropertyInitialization": true,
    "noImplicitThis": true,
    "alwaysStrict": true
  }
}

---

noImplicitAny

Require explicit types, no implicit any.

Without noImplicitAny (Dangerous)

function add(a, b) {  // Implicitly any
  return a + b;
}

add(5, 3);        // 8
add('5', '3');    // '53'  // No error!

With noImplicitAny

// ✗ Error: Parameter 'a' implicitly has an 'any' type
function add(a, b) {
  return a + b;
}

// Fix: Add types
function add(a: number, b: number): number {
  return a + b;
}

---

strictNullChecks

null and undefined are not assignable to other types.

Without strictNullChecks

function getUser(id: string): User {
  const user = database.find(id);
  return user;  // Might be undefined, but no error!
}

const user = getUser('123');
console.log(user.name.toUpperCase());  // Runtime crash if user is undefined!

With strictNullChecks

function getUser(id: string): User | null {
  const user = database.find(id);
  return user || null;
}

const user = getUser('123');
// console.log(user.name);  // ✗ Error: Object is possibly 'null'

// Fix: Check for null
if (user) {
  console.log(user.name.toUpperCase());
}

---

strictPropertyInitialization

Class properties must be initialized.

Without strictPropertyInitialization

class UserService {
  private apiKey: string;  // Never initialized!
  
  constructor() {
    // Forgot to set apiKey
  }
  
  fetchUser() {
    return fetch('/api/user', {
      headers: { 'X-API-Key': this.apiKey }  // undefined!
    });
  }
}

With strictPropertyInitialization

class UserService {
  // ✗ Error: Property 'apiKey' has no initializer
  private apiKey: string;
  
  constructor() {}
}

// Fix options:
// 1. Initialize in declaration
class UserService {
  private apiKey: string = process.env.API_KEY!;
}

// 2. Initialize in constructor
class UserService {
  private apiKey: string;
  
  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }
}

// 3. Use definite assignment assertion (if you know better than compiler)
class UserService {
  private apiKey!: string;  // Trust me, it'll be initialized
  
  constructor() {
    this.initialize();
  }
  
  private initialize() {
    this.apiKey = process.env.API_KEY!;
  }
}

---

Module Options

Configure module system and resolution.

module and moduleResolution

{
  "compilerOptions": {
    "module": "commonjs",        // Output format
    "moduleResolution": "node"   // How to find modules
  }
}

Common combinations:

// Node.js project
{
  "module": "commonjs",
  "moduleResolution": "node"
}

// Modern ES modules
{
  "module": "es2020",
  "moduleResolution": "node"
}

// Library for bundlers
{
  "module": "esnext",
  "moduleResolution": "node"
}

esModuleInterop

Allow importing CommonJS modules as ES modules.

{
  "compilerOptions": {
    "esModuleInterop": true
  }
}

// Without esModuleInterop
import * as express from 'express';
const app = express();

// With esModuleInterop (cleaner)
import express from 'express';
const app = express();

---

Target and Lib

target

JavaScript version to compile to.

{
  "compilerOptions": {
    "target": "ES2020"  // ES5, ES2015, ES2020, ESNext
  }
}

Impact on output:

// Source
const numbers = [1, 2, 3];
const doubled = numbers.map(n => n * 2);

// Target: ES5
var numbers = [1, 2, 3];
var doubled = numbers.map(function (n) { return n * 2; });

// Target: ES2020
const numbers = [1, 2, 3];
const doubled = numbers.map(n => n * 2);

lib

Include type definitions for runtime features.

{
  "compilerOptions": {
    "lib": ["ES2020", "DOM"]
  }
}

Common combinations:

// Node.js server
{
  "target": "ES2020",
  "lib": ["ES2020"]
}

// Browser app
{
  "target": "ES2020",
  "lib": ["ES2020", "DOM", "DOM.Iterable"]
}

// Web Worker
{
  "target": "ES2020",
  "lib": ["ES2020", "WebWorker"]
}

---

Path Configuration

baseUrl and paths

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"],
      "@services/*": ["src/services/*"]
    }
  }
}

// Instead of:
import { Button } from '../../../components/Button';

// Use:
import { Button } from '@components/Button';

Warning: Only affects TypeScript. Need bundler or path rewriter for runtime.

---

Source Maps

sourceMap

Generate .map files for debugging.

{
  "compilerOptions": {
    "sourceMap": true
  }
}

Enables debugging TypeScript in browser/Node:

Source:      src/app.ts
Compiled:    dist/app.js
Source map:  dist/app.js.map

Debugger shows original TypeScript, not compiled JavaScript.

inlineSourceMap

Embed source map in output file.

{
  "compilerOptions": {
    "inlineSourceMap": true
  }
}

Larger files, but no separate .map files.

---

Declaration Files

declaration

Generate .d.ts files for libraries.

{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true  // Source maps for .d.ts files
  }
}

Essential for publishing npm packages:

src/
  index.ts       // Source
dist/
  index.js       // Compiled
  index.d.ts     // Type definitions
  index.d.ts.map // Declaration source map

---

Additional Checks

Extra checks beyond strict mode.

noUnusedLocals and noUnusedParameters

{
  "compilerOptions": {
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

function processUser(user: User, options: Options) {
  // ✗ Error: 'options' is declared but never used
  console.log(user.name);
}

// Fix: Remove unused parameter or prefix with _
function processUser(user: User, _options: Options) {
  console.log(user.name);
}

noImplicitReturns

All code paths must return a value.

{
  "compilerOptions": {
    "noImplicitReturns": true
  }
}

// ✗ Error: Not all code paths return a value
function getUser(id: string): User {
  if (id === 'admin') {
    return adminUser;
  }
  // Missing return for non-admin case!
}

// Fix: Add else case
function getUser(id: string): User {
  if (id === 'admin') {
    return adminUser;
  }
  return guestUser;
}

noFallthroughCasesInSwitch

Switch cases must break or return.

{
  "compilerOptions": {
    "noFallthroughCasesInSwitch": true
  }
}

function processStatus(status: string): void {
  switch (status) {
    case 'pending':
      console.log('Processing...');
      // ✗ Error: Fallthrough case in switch
    case 'approved':
      console.log('Approved');
      break;
  }
}

// Fix: Add break
function processStatus(status: string): void {
  switch (status) {
    case 'pending':
      console.log('Processing...');
      break;
    case 'approved':
      console.log('Approved');
      break;
  }
}

---

Project References

For monorepos and large projects.

Basic Setup

// tsconfig.base.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true
  }
}

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

// packages/ui/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "references": [
    { "path": "../core" }
  ],
  "include": ["src/**/*"]
}

Build with references:

tsc --build packages/ui
# Automatically builds core first

---

Real-World Configs

Node.js Server

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "moduleResolution": "node",
    "sourceMap": true,
    "declaration": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

React App

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx",
    "module": "esnext",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src"]
}

NPM Library

{
  "compilerOptions": {
    "target": "ES2015",
    "module": "esnext",
    "lib": ["ES2020"],
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

---

Common Mistakes I Made

1. Not Enabling Strict Mode

Bad:

{
  "compilerOptions": {
    "strict": false  // Or omitting it (defaults to false)
  }
}

Result: TypeScript becomes JavaScript with extra steps.

Good:

{
  "compilerOptions": {
    "strict": true  // Catch real bugs
  }
}

2. Wrong Target for Environment

Bad (Node.js with ES5 target):

{
  "compilerOptions": {
    "target": "ES5"  // Node supports ES2020!
  }
}

Result: Slower code, larger bundles, polyfills for features Node has natively.

Good:

{
  "compilerOptions": {
    "target": "ES2020"  // Match your Node version
  }
}

3. Including Test Files in Build

Bad:

{
  "include": ["src/**/*"]  // Includes *.test.ts files!
}

Good:

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

---

Your Challenge

Create optimized tsconfig for different environments:

project/
  src/
    server/
    client/
    shared/
  tsconfig.base.json
  tsconfig.server.json
  tsconfig.client.json

Requirements:

1. Base config with shared options

2. Server config:

   • Node.js target

   • CommonJS modules

   • Strict mode

   • Source maps

3. Client config:

   • Browser target

   • ES modules

   • React support

   • Path aliases

4. Shared types usable by both

Bonus: Add project references for incremental builds.

---

Key Takeaways

1. Enable strict mode - catches real bugs

2. Match target to runtime - don't over-transpile

3. Use path aliases - cleaner imports (with bundler)

4. Generate source maps - debuggable code

5. Project references - faster builds in monorepos

6. Additional checks - noUnusedLocals, noImplicitReturns

7. Extend base config - share common settings

8. skipLibCheck - faster builds, ignore .d.ts errors

---

What I Learned

Enabling strict: true found 227 errors in our codebase.

Every single one was a real bug:

• Null reference errors waiting to crash

• Type mismatches silently passing through

• Uninitialized properties causing undefined behavior

3 days to fix them all. 14 production bugs prevented.

The lesson: TypeScript without strict mode is glorified documentation. It catches typos, but not logic errors.

With strict mode:

function getUser(id: string): User | null {  // Forces handling null
  const user = database.find(id);
  return user || null;
}

const user = getUser('123');
if (user) {  // Compiler forces this check
  console.log(user.name);
}

Without strict mode:

function getUser(id: string): User {  // Lies! Might be undefined
  const user = database.find(id);
  return user;  // Compiles fine, crashes at runtime
}

Configuration isn't just settings - it's your safety net.

The strictest config is the kindest to your future self. Enable strict: true on day one. Every error caught at compile time is a bug prevented in production.

Make the compiler your ally. Configure it to be ruthless.

---

Next: Type Assertions and Narrowing

In the next article, we'll explore type assertions and advanced narrowing techniques. You'll learn when to override the compiler and when that's a terrible idea.