TypeScript Compiler Configuration: Production-Ready Reference

Critical Performance Optimizations

Essential Speed Settings

• skipLibCheck: true - Single biggest performance win (30-50% faster builds)
• incremental: true - For development only, disable in CI/CD
• tsBuildInfoFile: "./tmp/.tsbuildinfo" - Store incremental data separately
• Memory allocation: NODE_OPTIONS="--max-old-space-size=8192" (8GB minimum for 20k+ lines)

Build Time Thresholds

• <5k lines: Default settings acceptable
• 5-20k lines: Requires skipLibCheck and memory tuning
• 20-50k lines: Project references mandatory for monorepos
• 50k+ lines: Consider architectural split if build >15 minutes

Configuration Patterns by Environment

Development Configuration

{
  "compilerOptions": {
    "sourceMap": true,
    "noEmitOnError": false,
    "incremental": true,
    "skipLibCheck": true,
    "removeComments": false,
    "preserveWatchOutput": true
  },
  "watchOptions": {
    "watchFile": "useFsEvents",
    "excludeDirectories": ["**/node_modules", "**/dist", "**/coverage"]
  }
}

Production Configuration

{
  "compilerOptions": {
    "sourceMap": false,
    "noEmitOnError": true,
    "incremental": false,
    "declaration": true,
    "removeComments": true,
    "skipLibCheck": true
  }
}

CI/CD Configuration

{
  "compilerOptions": {
    "noEmitOnError": true,
    "skipLibCheck": true,
    "incremental": false,
    "tsBuildInfoFile": null,
    "pretty": false
  }
}

Strict Mode Migration Strategy

Phase 1: Foundation (Week 1-2)

• Start with "strict": false
• Enable "noImplicitAny": true only
• Fix resulting errors before proceeding

Phase 2: Null Safety (Week 3-4)

• Enable "strictNullChecks": true
• Impact: Moderate error count, worth the safety

Phase 3: Advanced (Month 2+)

• "strictFunctionTypes": true
• "strictPropertyInitialization": true
• Warning: exactOptionalPropertyTypes finds edge cases in React props

Enterprise Failure Pattern

• Teams enabling "strict": true immediately experience 300+ errors
• Result: Development paralysis for weeks, often abandon TypeScript

Memory Management and Performance

Memory Requirements by Project Size

Project Size	Memory Needed	Common Issues
<5k lines	Default (1-2GB)	Rare crashes
5-20k lines	8GB	VS Code crashes
20-50k lines	12-16GB	Build timeouts
50k+ lines	16GB+	Architectural problems

VS Code Crash Prevention

{
  "typescript.preferences.includePackageJsonAutoImports": "off",
  "typescript.suggest.autoImports": false,
  "typescript.disableAutomaticTypeAcquisition": true
}

Build Performance Debugging

# Generate trace for Chrome DevTools analysis
tsc --generateTrace trace --project .

# Extended diagnostics for timing breakdown
tsc --extendedDiagnostics --noEmit

# Memory usage monitoring
export NODE_OPTIONS="--max-old-space-size=8192"

Monorepo Configuration (Project References)

Setup Requirements

• Setup time: 1-2 weeks initial configuration
• Performance gain: 60-80% faster builds after setup
• Complexity: High, requires composite: true everywhere

Root Configuration

{
  "files": [],
  "references": [
    { "path": "./packages/shared" },
    { "path": "./packages/app" }
  ]
}

Package Configuration

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

Build Command

tsc --build --verbose

Path Mapping: Configuration and Pitfalls

Safe Path Configuration

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

Critical Warnings

• Webpack: Requires additional resolve.alias configuration
• Jest: Needs moduleNameMapping setup
• Production: Path mapping is TypeScript-only, runtime needs separate config
• Failure mode: Silent import failures, difficult to debug

Runtime Integration Requirements

• webpack: resolve.alias configuration
• Node.js: module-alias or tsconfig-paths
• Vite: Built-in support
• Testing: Jest moduleNameMapping

Advanced Type Checking Options

Balanced Strictness (Recommended)

{
  "compilerOptions": {
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noImplicitThis": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  }
}

Maximum Safety (Performance Impact)

{
  "compilerOptions": {
    "exactOptionalPropertyTypes": true,
    "noPropertyAccessFromIndexSignature": true,
    "noUncheckedIndexedAccess": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

Performance vs Safety Trade-offs

• exactOptionalPropertyTypes: Catches edge cases but slows development
• noUncheckedIndexedAccess: Prevents runtime errors but verbose
• Impact: 30% slower development for 60% fewer runtime errors

Common Configuration Failures

Incremental Build Failures

• CI/CD environments: Disable incremental builds completely
• Docker: Cache invalidation breaks builds randomly
• Symptoms: Phantom errors, inconsistent builds
• Solution: "incremental": false in production

Memory Exhaustion Patterns

• Symptoms: "JavaScript heap out of memory", VS Code crashes
• Threshold: 15-16GB consumption on large projects
• Solutions: Increase Node memory, simplify types, split projects

Path Resolution Failures

• Development works, production fails: Missing runtime path resolution
• Test failures: Jest doesn't understand TypeScript paths
• Debugging: Test import resolution in target environment

Migration Strategy: JavaScript to TypeScript

Week 1-2: Infrastructure

1. Install TypeScript with "allowJs": true
2. Configure build tools for .js/.ts coexistence
3. Create basic tsconfig.json

Week 3-4: Utilities First

1. Convert utility functions (.js → .ts)
2. Add basic type annotations
3. Fix obvious type errors

Month 2: Component Migration

1. Convert React components
2. Type props and state
3. Add interface definitions

Month 3+: Strictness

1. Enable strict checks incrementally
2. Remove any types systematically
3. Add advanced type safety

Success Metrics

• 80% higher adoption success with gradual approach
• 30% development slowdown initially, 20% faster long-term
• Critical mass: 10k+ lines where TypeScript benefits outweigh costs

Tool Integration Patterns

Watch Mode Optimization

{
  "watchOptions": {
    "watchFile": "useFsEvents",
    "excludeDirectories": [
      "**/node_modules",
      "**/.git",
      "**/dist",
      "**/coverage"
    ]
  }
}

Docker Build Optimization

# Multi-stage build pattern
FROM node:18-alpine AS builder
COPY package*.json ./
RUN npm ci --only=production
COPY tsconfig.json src/ ./
RUN npm run build

FROM node:18-alpine
COPY --from=builder /app/dist ./dist

Testing Configuration

{
  "compilerOptions": {
    "types": ["jest", "@testing-library/jest-dom"],
    "allowJs": true,
    "isolatedModules": false
  },
  "include": ["**/*.test.ts", "**/*.spec.ts"]
}

Version-Specific Considerations

TypeScript 5.0+ Features

• Performance improvements: Enables stricter settings without penalty
• Incremental compilation: Fixed major bugs in 5.1+
• Memory management: 20-30% reduction in 5.5+

Breaking Changes Impact

• 5.0: Decorator changes affect Angular projects
• 5.1: Module resolution changes
• 5.2: Performance improvements for large projects
• 5.9: Latest stable with comprehensive improvements

Decision Criteria

When to Use TypeScript

• Project size: >10k lines of code
• Team size: Multiple developers
• Maintenance duration: Long-term projects
• Error tolerance: Low tolerance for runtime errors

When to Avoid TypeScript

• Build time: >15 minutes after optimization
• Team resistance: >30% time spent on type issues
• Project scope: Rapid prototyping, small utilities
• Deadline pressure: Type safety luxury vs shipping

Resource Investment

• Learning curve: 2-3 weeks for team proficiency
• Initial setup: 1-2 weeks for complex projects
• Ongoing maintenance: 10-15% additional development time
• Long-term benefit: 20% faster development after 6 months

Critical Failure Modes

Production Build Failures

• Cause: Different configs between dev/prod
• Prevention: Test production config in CI/CD
• Recovery: Separate type checking from transpilation

Memory Exhaustion

• Trigger: Complex type computations, large codebases
• Symptoms: Builds hang, VS Code crashes
• Mitigation: Memory allocation, project splitting

Incremental Build Corruption

• Trigger: File system changes, compiler updates
• Symptoms: Inconsistent errors, phantom failures
• Recovery: Delete .tsbuildinfo, full rebuild

Resource Requirements

Team Expertise Needed

• Basic TypeScript: 1-2 developers minimum
• Advanced configuration: 1 expert for complex setups
• Debugging skills: Understanding compiler internals
• Tool integration: Webpack/Vite/build tool knowledge

Time Investment

• Initial migration: 1-3 months depending on codebase size
• Configuration optimization: 2-4 weeks
• Team training: 4-6 weeks for proficiency
• Maintenance overhead: 10-15% ongoing development time

Infrastructure Requirements

• CI/CD capacity: 2-3x build time initially
• Development machines: 16GB+ RAM for large projects
• Build servers: High-memory instances for monorepos