typescript

name

typescript

description

TypeScript performance, tsconfig, type errors, async patterns — triggered when the user asks to "optimize TypeScript performance", "speed up tsc compilation", "configure tsconfig.json", "fix type errors", "improve async patterns", or encounters TS errors (TS2322, TS2339, "is not assignable to"). Also triggers on .ts, .tsx, .d.ts file work involving type definitions, module organization, or memory management. Does NOT cover TypeScript basics, framework-specific patterns, or testing.

TypeScript Best Practices

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

When to Apply

Reference these guidelines when:

• Configuring tsconfig.json for a new or existing project
• Writing complex type definitions or generics
• Optimizing async/await patterns and data fetching
• Organizing modules and managing imports
• Reviewing code for compilation or runtime performance

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Type System Performance	CRITICAL	type-
2	Compiler Configuration	CRITICAL	tscfg-
3	Async Patterns	HIGH	async-
4	Module Organization	HIGH	module-
5	Type Safety Patterns	MEDIUM-HIGH	safety-
6	Memory Management	MEDIUM	mem-
7	Runtime Optimization	LOW-MEDIUM	runtime-
8	Advanced Patterns	LOW	advanced-

Table of Contents

1. Type System Performance — CRITICAL
   • 1.1 Add Explicit Return Types to Exported Functions — CRITICAL (30-50% faster declaration emit)
   • 1.2 Avoid Deeply Nested Generic Types — CRITICAL (prevents exponential instantiation cost)
   • 1.3 Avoid Large Union Types — CRITICAL (quadratic O(n²) comparison cost)
   • 1.4 Extract Conditional Types to Named Aliases — CRITICAL (enables compiler caching, prevents re-evaluation)
   • 1.5 Limit Type Recursion Depth — HIGH (prevents exponential type expansion when applicable)
   • 1.6 Prefer Interfaces Over Type Intersections — CRITICAL (2-5× faster type resolution)
   • 1.7 Simplify Complex Mapped Types — HIGH (reduces type computation by 50-80% when applicable)
2. Compiler Configuration — CRITICAL
   • 2.1 Configure Include and Exclude Properly — CRITICAL (prevents scanning thousands of unnecessary files)
   • 2.2 Enable Incremental Compilation — CRITICAL (50-90% faster rebuilds)
   • 2.3 Enable isolatedDeclarations for Parallel Declaration Emit — CRITICAL (enables parallel .d.ts generation without type-checker)
   • 2.4 Enable skipLibCheck for Faster Builds — CRITICAL (20-40% faster compilation)
   • 2.5 Enable strictFunctionTypes for Faster Variance Checks — CRITICAL (enables optimized variance checking)
   • 2.6 Use erasableSyntaxOnly for Node.js Native TypeScript — HIGH (prevents 100% of Node.js type-stripping runtime errors)
   • 2.7 Use isolatedModules for Single-File Transpilation — CRITICAL (80-90% faster transpilation with bundlers)
   • 2.8 Use Project References for Large Codebases — CRITICAL (60-80% faster incremental builds)
3. Async Patterns — HIGH

References

1. https://github.com/microsoft/TypeScript/wiki/Performance
2. https://www.typescriptlang.org/docs/handbook/
3. https://v8.dev/blog
4. https://nodejs.org/en/learn/diagnostics/memory