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

``bash
npm install -g typescript-performance-analyzer
`

Or run directly with npx:

`bash
npx typescript-performance-analyzer trace
`

Quick Start

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

`bash
tpa trace --open
`

Or specify a project path:

`bash
tpa trace ./my-project --open
`

Commands

$3

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

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

Examples:

`bash


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
`

$3

Generate HTML report from existing trace files.

`bash
tpa analyze [options]
`

Arguments:

- : Directory containing trace.json and types.json

Options:

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

Examples:

`bash


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
`

$3

Show quick summary in terminal without generating HTML.

`bash
tpa summary [options]
`

Arguments:

- : Directory containing trace.json

Options:

| Option | Description | Default |
| ----------- | ------------------------------- | ------- |
| --top | 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