TypeScript Performance Best Practices

Comprehensive performance optimization guide for TypeScript codebases. Contains 43 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing or refactoring TypeScript code
• Tuning build times, type-checking performance, declaration emit, or editor responsiveness
• Investigating performance regressions
• Reviewing code for performance issues
• Configuring tsconfig.json for new projects or monorepos

Quick Diagnostic Workflow

When TypeScript feels slow, follow this diagnostic sequence:

# Step 1: Get baseline metrics
tsc --extendedDiagnostics --noEmit

# Key metrics to check:
# - Files: Should match expected source count
# - Check time: Usually the bottleneck (>10s is high)
# - Instantiations: High count indicates complex generics

# Step 2: If file count is high
tsc --listFiles | wc -l
tsc --explainFiles 2>&1 | grep -v "@types" | head -50

# Step 3: If Check time is high
tsc --generateTrace ./trace --noEmit
# Open chrome://tracing and load trace/trace.json

# Step 4: If module resolution is slow
tsc --traceResolution 2>&1 | head -200

Rule Categories by Priority

Common Scenarios

Scenario: Slow CI Builds (>60s)

Symptoms: CI takes minutes, incremental doesn't help

Diagnostic:

tsc --extendedDiagnostics --noEmit
# Check: Files count, Check time, Memory used

Likely fixes:

1. Enable incremental: true with cached .tsbuildinfo
2. Enable skipLibCheck: true (10-50% improvement)
3. Split into project references (60-70% memory reduction)
4. Narrow include patterns

Scenario: Slow Editor/IntelliSense

Symptoms: Autocomplete lags, hover takes seconds, high memory

Diagnostic:

# Check tsserver memory
ps aux | grep tsserver | awk '{print $6/1024 " MB"}'

Likely fixes:

1. Enable disableReferencedProjectLoad: true
2. Enable disableSolutionSearching: true
3. Enable disableSourceOfProjectReferenceRedirect: true
4. Split into project references

Scenario: Type Checking Takes >10s

Symptoms: Check time dominates in diagnostics

Diagnostic:

tsc --generateTrace ./trace --noEmit
# Open chrome://tracing, find slow checkSourceFile operations

Likely fixes:

1. Add explicit return type annotations to exported functions
2. Simplify large unions (50+ members)
3. Replace deep intersections with interface extension
4. Name complex types with type aliases

Scenario: Unexpected Files in Build

Symptoms: More files than expected, node_modules source compiled

Diagnostic:

tsc --explainFiles 2>&1 | grep -v "@types" | grep "node_modules"

Likely fixes:

1. Add "exclude": ["node_modules", "dist"]
2. Narrow include to ["src"]
3. Remove broad **/* patterns

Quick Reference

1. Build Graph & Incremental (CRITICAL)

Impact: 50-80% faster rebuilds; essential for monorepos

2. Program Scope & Inputs (HIGH)

Impact: Reduces files parsed; every extra file costs time

3. Module Resolution & Imports (HIGH)

Impact: Reduces resolution overhead; wrong mode = excessive lookups

4. Type Acquisition & Lib Checks (MEDIUM-HIGH)

Impact: 10-50% faster type-checking; skips redundant work

5. Type System Complexity (CRITICAL)

Impact: Complex types cause O(n^2) checking; simplification = big wins

6. Declaration Emit & Public API (MEDIUM-HIGH)

Impact: Up to 3x faster with isolatedDeclarations (requires --noCheck or alternative emitters like swc/oxc to benefit); parallel emit

7. Editor/tsserver Performance (MEDIUM-HIGH)

Impact: ~3GB to <1GB memory; faster startup, navigation

8. Diagnostics & Profiling (DIAGNOSTIC)

Purpose: Tools for finding performance issues, not optimizations themselves

Recommended Base Configuration

For most TypeScript projects:

{
  "compilerOptions": {
    // Performance essentials
    "incremental": true,
    "skipLibCheck": true,
    "moduleResolution": "bundler",

    // For libraries
    "declaration": true,
    "declarationMap": true,
    "isolatedDeclarations": true,

    // Standard strictness
    "strict": true,
    "noUncheckedIndexedAccess": true,

    // Output
    "target": "ES2022",
    "module": "ESNext"
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

For monorepos, add to each package:

{
  "compilerOptions": {
    "composite": true,
    "disableReferencedProjectLoad": true,
    "disableSolutionSearching": true,
    "disableSourceOfProjectReferenceRedirect": true
  }
}

TypeScript 5.6+ Performance Features

Recent TypeScript versions (5.6-5.8) introduced significant performance improvements:

--noCheck Flag (TS 5.6+)

Skip type-checking when you only need transpilation or declaration emit:

# Fast declaration emit without type-checking
tsc --declaration --emitDeclarationOnly --noCheck

# Combine with isolatedDeclarations for maximum speed
tsc --declaration --emitDeclarationOnly --noCheck --isolatedDeclarations

When to use: CI pipelines where type-checking runs separately, or when using swc/esbuild for transpilation.

--libReplacement Flag (TS 5.8+)

Control whether lib.d.ts can be replaced by node_modules types:

{
  "compilerOptions": {
    "libReplacement": false
  }
}

Impact: Prevents unexpected type resolution slowdowns from packages that ship their own lib replacements.

Version Compatibility Table

TypeScript 7 Preview (Experimental)

TypeScript 7, currently in development, is being rewritten in Go for significantly faster compilation. Early benchmarks suggest:

• 10x faster type-checking in large codebases
• 5x faster editor responsiveness
• Full backward compatibility with TS 5.x configs

Status (as of January 2026): Preview builds available. Not production-ready. Monitor TypeScript 7 roadmap for updates.

How to Use

Read individual rule files for detailed explanations and code examples:

rules/build-project-references.md
rules/type-annotate-returns.md
rules/diag-generate-trace.md

Each rule file contains:

• Impact rating with quantified description
• Why it matters with numbered benefits
• Incorrect/Correct code examples
• When NOT to apply (important for avoiding over-optimization)
• Common mistakes to avoid
• Diagnostic commands for verification
• References to official documentation

References

• TypeScript Performance Wiki
• TypeScript tsconfig Reference
• TypeScript Project References
• TypeScript 5.5 isolatedDeclarations
• TypeScript 5.6 Release Notes
• TypeScript 5.8 Release Notes
• TypeScript 7 Roadmap (Go Rewrite)