tpa - TypeScript Performance Analyzer

Analyze TypeScript compiler performance by parsing --generateTrace output and generating interactive HTML reports.

Why TPA?

As TypeScript projects grow, compilation times increase dramatically. While TypeScript provides the --generateTrace option to generate compilation traces, manually analyzing tens of megabytes of JSON files is practically impossible.

TPA solves this problem:

• One Command: Run tpa trace --open to generate traces and analyze them in one step
• Instant Insights: Immediately identify which files are slowing down your compilation
• Detailed Analysis: Time breakdown for each phase - Parse, Bind, Check, and Emit
• Source Code Context: View actual code snippets at slow locations
• Large File Support: Memory-efficient streaming parser handles large trace files

Installation

In your project

npm install -g typescript-performance-analyzer

Or run directly with npx:

npx typescript-performance-analyzer trace

Quick Start

Run in your TypeScript project directory to generate trace and analyze:

tpa trace --open

Or specify a project path:

tpa trace ./my-project --open

Commands

tpa trace - One-step Analysis

Run trace generation and HTML report generation in a single command.

tpa trace [project-path] [options]

Arguments:

• [project-path]: Path to TypeScript project (containing tsconfig.json). Defaults to current directory (.)

Options:

| Option | Description | Default | | ---------------------- | ----------------------------------------- | ------------------------- | | -o, --output <path> | Output HTML file path | ./tsc-report.html | | --open | Open report in browser after generation | - | | --min-duration <ms> | Filter events shorter than threshold (ms) | 0.1 | | --top <n> | Number of hotspot files to show | 20 | | -v, --verbose | Show detailed progress and tsc output | - | | --snippet-length <n> | Maximum code snippet length | 200 | | --trace-dir <path> | Custom directory for trace output | .tsc-trace (in project) | | --keep-trace | Keep trace files after analysis | cleanup | | --tsc-args <args> | Additional arguments to pass to tsc | - |

Examples:

# Analyze current directory
tpa trace --open

# Analyze specific project
tpa trace ./my-project --open

# Run with skipLibCheck
tpa trace --tsc-args "--skipLibCheck" --open

# Keep trace files after analysis
tpa trace --keep-trace -o analysis.html

tpa analyze - Generate HTML Report

Generate HTML report from existing trace files.

tpa analyze <trace-dir> [options]

Arguments:

• <trace-dir>: Directory containing trace.json and types.json

Options:

| Option | Description | Default | | ---------------------- | --------------------------------------------- | ------------------- | | -o, --output <path> | Output HTML file path | ./tsc-report.html | | --open | Open report in browser after generation | - | | --min-duration <ms> | Filter events shorter than threshold (ms) | 0.1 | | --top <n> | Number of hotspot files to show | 20 | | -p, --project <path> | Project root path for code snippet extraction | - | | --snippet-length <n> | Maximum code snippet length | 200 | | -v, --verbose | Show detailed progress | - |

Examples:

# First, generate trace
tsc --generateTrace ./trace-log

# Run analysis
tpa analyze ./trace-log -o report.html --open

# Analyze with code snippets
tpa analyze ./trace-log -o report.html --project /path/to/project --open

tpa summary - Terminal Summary

Show quick summary in terminal without generating HTML.

tpa summary <trace-dir> [options]

Arguments:

• <trace-dir>: Directory containing trace.json

Options:

| Option | Description | Default | | ----------- | ------------------------------- | ------- | | --top <n> | Number of hotspot files to show | 10 |

Example Output:

══════════════════════════════════════════════════
  TypeScript Compilation Summary
══════════════════════════════════════════════════

📊 Overview
   Total Duration: 56.69s
   Files Processed: 14,361
   Total Events: 46,011

⏱️  Phase Breakdown
   Parse    ░░░░░░░░░░░░░░░░░░░░░░░░░      1.72s (1.6%)
   Bind     ░░░░░░░░░░░░░░░░░░░░░░░░░      1.13s (1.1%)
   Check    █████████████████████░░░░   1m 31.0s (84.9%)
   Emit     ███░░░░░░░░░░░░░░░░░░░░░░     13.37s (12.5%)

🔥 Top 10 Slowest Files
    1.      1.07s  .../useColDefFactory.tsx
    2.   987.47ms  .../ImperativeDialogInstanceContent.tsx
    ...

HTML Report Features

The generated HTML report includes:

• Overview Statistics: Total duration, files processed, event count
• Hotspot Table: Slowest files with phase breakdown and search/sort
• Location Analysis: Slow code locations with SyntaxKind and snippets
• UI Features: Dark/Light theme, collapsible sidebar, offline support

Understanding Compilation Phases

| Phase | Description | | --------- | ------------------------------------------- | | Parse | Lexing and parsing source files into ASTs | | Bind | Binding declarations and setting up symbols | | Check | Type checking (usually the slowest phase) | | Emit | Generating JavaScript output files |

License

MIT