Agent Skills: TypeScript Performance Analysis and Optimization

TypeScript Performance Analysis and Optimization

This skill provides a systematic approach to diagnosing and resolving TypeScript performance issues through data-driven analysis.

Core Principle: Always Start with Diagnostics

Never guess at performance issues. Always collect diagnostic data first:

1. For build performance: Run --extendedDiagnostics or generate a performance trace
2. For editor performance: Collect TS Server logs
3. For configuration issues: Use --listFilesOnly and --explainFiles

Quick Start Workflow

1. Identify the Problem Type

Ask user to clarify:

• Build performance: tsc or bundler compilation is slow
• Editor performance: VS Code autocomplete/type-checking is slow
• Both: Likely a fundamental type-checking issue

2. Collect Diagnostic Data

For Build Performance Issues

Quick Diagnostics:

npx tsc -p . --extendedDiagnostics

Use scripts/analyze_diagnostics.py to parse and interpret the output:

npx tsc -p . --extendedDiagnostics 2>&1 | python scripts/analyze_diagnostics.py -

Detailed Analysis (if needed):

# Generate comprehensive trace
bash scripts/generate_trace.sh . ./trace_output

# Quick automated analysis
npx @typescript/analyze-trace ./trace_output

# Visual analysis in Chrome/Edge
# Open about://tracing and load trace_output/trace.*.json

For Editor Performance Issues

Get TS Server log in VS Code:

1. Command Palette → TypeScript: Open TS Server log
2. Enable logging if prompted
3. Reproduce the slow behavior
4. Return to get the log file

Check for common issues:

• High memory usage → Project too large
• Slow responses → Specific file/operation issue
• Frequent errors → Configuration problem

3. Analyze the Data

Interpreting extendedDiagnostics

Use analyze_diagnostics.py output to identify:

• High Check time (>70% of total): Type-checking bottleneck → Generate trace for detailed analysis

• High I/O Read time (>30% of total): File system issue → Check include/exclude configuration

• High file count (>2000): Configuration problem → Review tsconfig.json patterns

• High memory usage (>2GB): Project size issue → Consider project references

Interpreting Performance Traces

For detailed trace analysis guidance, read references/trace-analysis-guide.md.

Key steps:

1. Load trace in about://tracing or use @typescript/analyze-trace
2. Focus on the Checking phase (usually the bottleneck)
3. Identify wide boxes with high "Wall Duration"
4. Look for patterns:
   • Specific files taking excessive time
   • Repeated type instantiations
   • Deep call stacks in type-checking

4. Apply Optimizations

Based on diagnostic findings, consult references/performance-checklist.md for specific optimizations.

Common Fix Patterns

Configuration Issues (High I/O time, high file count):

• Fix include/exclude patterns
• Limit @types auto-inclusion
• Enable skipLibCheck

Type-Checking Issues (High Check time):

• Prefer interfaces over type intersections
• Add explicit return types
• Extract complex conditional types
• Use subtypes instead of large unions

Project Structure Issues (High memory, very large projects):

• Implement project references
• Split monolithic projects
• Separate test code

Build Tool Issues:

• Enable isolatedModules
• Use faster transpilers (esbuild/swc)
• Separate type-checking from transpilation

5. Verify Improvements

After applying fixes:

1. Re-run diagnostics to measure improvement
2. Compare before/after metrics
3. Ensure functionality is unchanged

Common Issues Reference

For specific problem patterns and solutions, read references/common-issues.md.

Common issues covered:

• node_modules being scanned
• Too many @types packages included
• Slow type-checking of specific code patterns
• Build tool integration slowness
• Memory usage problems
• Incremental builds not helping

Using the Scripts

generate_trace.sh

Generates a complete performance trace with diagnostics:

bash scripts/generate_trace.sh [project-path] [output-dir]

Default: current directory, output to ./trace_output

Output includes:

• trace.*.json files (load in about://tracing)
• types.*.json files (type information)
• diagnostics.txt (extendedDiagnostics output)

analyze_diagnostics.py

Parses and analyzes extendedDiagnostics output:

# From file
python scripts/analyze_diagnostics.py diagnostics.txt

# From pipe
tsc --extendedDiagnostics 2>&1 | python scripts/analyze_diagnostics.py -

Provides:

• Key metrics summary
• Time breakdown with percentages
• Automated issue detection
• Specific recommendations

Advanced Analysis

For complex cases requiring deep investigation:

1. Review trace-analysis-guide.md for detailed trace interpretation
2. Cross-reference with types.json to understand type structures
3. Use Chrome DevTools Performance tab as alternative to about://tracing
4. Generate CPU profiles with --generateCpuProfile for compiler profiling

When to File an Issue

File a TypeScript issue if:

• Minimal reproduction case exists
• Diagnostics and trace data collected
• Issue persists on latest TypeScript version
• Solutions in this skill don't resolve the problem

Include:

• TypeScript version (npx tsc -v)
• Node version (node -v)
• extendedDiagnostics output
• Performance trace files (if applicable)
• Minimal reproduction code