typescript

TypeScript Best Practices

Comprehensive TypeScript 7-compatible guide with 44 rules across 8 categories, covering compiler configuration, type-system performance, async code, modules, safety, and measured runtime optimization.

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

Table of Contents

1. Type System Performance — CRITICAL

• 1.1 Add Explicit Return Types to Exported Functions — CRITICAL (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 — CRITICAL (prevents exponential type expansion)
• 1.6 Prefer Interfaces Over Type Intersections — CRITICAL (faster type resolution)
• 1.7 Simplify Complex Mapped Types — CRITICAL (reduces type computation)

1. Compiler Configuration — CRITICAL

• 2.1 Configure Include and Exclude Properly — CRITICAL (prevents scanning thousands of unnecessary files)
• 2.2 Enable Incremental Compilation — CRITICAL (faster rebuilds)
• 2.3 Choose skipLibCheck Deliberately — CRITICAL (faster compilation)
• 2.4 Enable strictFunctionTypes for Sound Function Assignments — CRITICAL (enables optimized variance checking)
• 2.5 Use isolatedModules for Single-File Transpilers — CRITICAL (faster transpilation with bundlers)
• 2.6 Use Project References for Large Codebases — CRITICAL (faster incremental builds)
• 2.7 Migrate TypeScript 7 Configuration Deliberately — CRITICAL

1. Async Patterns — HIGH

• 3.1 Annotate Async Function Return Types — HIGH (prevents runtime errors, improves inference)
• 3.2 Avoid await Inside Loops — HIGH (scales linearly with the number of iterations)
• 3.3 Avoid Unnecessary async/await — HIGH (eliminates microtask queue overhead)
• 3.4 Defer await Until Value Is Needed — HIGH (enables implicit parallelization)
• 3.5 Use Promise.all for Independent Operations — HIGH (improvement in I/O-bound code)

1. Module Organization — HIGH

• 4.1 Avoid Barrel File Imports — HIGH (import cost, larger bundles)
• 4.2 Avoid Circular Dependencies — HIGH (prevents runtime undefined errors and slow compilation)
• 4.3 Control @types Package Inclusion — HIGH (prevents type conflicts and reduces memory usage)
• 4.4 Use Dynamic Imports for Large Modules — HIGH (reduces initial bundle)
• 4.5 Use Type-Only Imports for Types — HIGH (eliminates runtime imports for type information)

1. Type Safety Patterns — MEDIUM-HIGH

• 5.1 Enable strictNullChecks — MEDIUM-HIGH
• 5.2 Prefer unknown Over any — MEDIUM-HIGH
• 5.3 Use Assertion Functions for Validation — MEDIUM-HIGH
• 5.4 Use const Assertions for Literal Types — MEDIUM-HIGH
• 5.5 Use Exhaustive Checks for Union Types — MEDIUM-HIGH
• 5.6 Use Type Guards for Runtime Type Checking — MEDIUM-HIGH

1. Memory Management — MEDIUM

• 6.1 Avoid Closure Memory Leaks — MEDIUM (prevents retained references in long-lived callbacks)
• 6.2 Avoid Global State Accumulation — MEDIUM (prevents unbounded memory growth)
• 6.3 Clean Up Event Listeners — MEDIUM (prevents unbounded memory growth)
• 6.4 Clear Timers and Intervals — MEDIUM (prevents callback retention and repeated execution)
• 6.5 Use WeakMap for Object Metadata — MEDIUM (prevents memory leaks, enables automatic cleanup)

1. Runtime Optimization — LOW-MEDIUM

• 7.1 Avoid Object Spread in Hot Loops — LOW-MEDIUM
• 7.2 Hoist Loop-Invariant Work in Measured Hot Paths — LOW-MEDIUM
• 7.3 Prefer Native Array Methods Over Lodash — LOW-MEDIUM
• 7.4 Use for-of for Simple Iteration — LOW-MEDIUM
• 7.5 Use Modern String Methods — LOW-MEDIUM
• 7.6 Use Set/Map for O(1) Lookups — LOW-MEDIUM

1. Advanced Patterns — LOW

• 8.1 Use Branded Types for Type-Safe IDs — LOW (prevents mixing incompatible ID types)
• 8.2 Use satisfies for Type Validation with Inference — LOW (prevents property access errors, enables reliable autocomplete)
• 8.3 Use Template Literal Types for String Patterns — LOW (prevents string format errors at compile time)

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