TypeScript Refactor Best Practices

Comprehensive TypeScript and TSX refactoring and modernization guide designed for AI agents and LLMs. Contains 47 rules across 9 categories, prioritized by impact to guide automated refactoring, code review, and code generation. Current to TypeScript 6.0 and React 19.

When to Apply

Reference these guidelines when:

• Refactoring TypeScript or React/TSX code for type safety and maintainability
• Designing type architectures (discriminated unions, branded types, generics)
• Narrowing types to eliminate unsafe as casts
• Typing React components and hooks (props, refs, events, state) in .tsx files
• Adopting modern TypeScript 5.x–6.0 features (satisfies, using, const type parameters, inferred type predicates, erasable syntax, with import attributes)
• Optimizing compiler performance in large codebases (isolatedDeclarations, project references)
• Implementing type-safe error handling patterns
• Reviewing code for TypeScript quirks and pitfalls

Rule Categories by Priority