Typescript Refactor

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

Quick Reference

1. Type Architecture (CRITICAL)

• arch-discriminated-unions [blocked] — Use discriminated unions over string enums for exhaustive pattern matching
• arch-branded-types [blocked] — Use branded types for domain identifiers to prevent value mix-ups
• arch-satisfies-over-annotation [blocked] — Use satisfies for config objects to preserve literal types
• arch-interfaces-over-intersections [blocked] — Extend interfaces instead of intersecting types for better error messages
• arch-const-assertion [blocked] — Use as const for immutable literal inference
• arch-readonly-by-default [blocked] — Default to readonly types for function parameters and return values
• arch-avoid-partial-abuse [blocked] — Avoid Partial<T> abuse for builder patterns

2. Type Narrowing & Guards (CRITICAL)

• narrow-custom-type-guards [blocked] — Replace as with runtime-checked guards; TS 5.5+ infers the predicate
• narrow-assertion-functions [blocked] — Use assertion functions for precondition checks
• narrow-exhaustive-switch [blocked] — Enforce exhaustive switch with never
• narrow-in-operator [blocked] — Narrow with the in operator for interface unions
• narrow-eliminate-as-casts [blocked] — Eliminate as casts with proper narrowing chains

3. Modern TypeScript (HIGH)

• modern-using-keyword [blocked] — Use the using keyword for resource cleanup
• modern-const-type-parameters [blocked] — Use const type parameters for literal inference
• modern-template-literal-types [blocked] — Use template literal types for string patterns
• modern-noinfer-utility [blocked] — Use NoInfer to control type parameter inference
• modern-verbatim-module-syntax [blocked] — Enable verbatimModuleSyntax for explicit import types
• modern-erasable-syntax [blocked] — Prefer erasable syntax over enums and namespaces for type-stripping
• modern-import-attributes [blocked] — Use with import attributes instead of deprecated assert

4. React & TSX (HIGH)

• tsx-avoid-react-fc [blocked] — Type props directly instead of React.FC
• tsx-ref-as-prop [blocked] — Pass ref as a prop instead of forwardRef (React 19)
• tsx-extend-native-props [blocked] — Extend native element props with ComponentPropsWithRef instead of redeclaring them
• tsx-discriminated-props [blocked] — Model mutually-exclusive props as discriminated unions
• tsx-event-handler-types [blocked] — Type event handlers with React synthetic event types
• tsx-hook-typing [blocked] — Type useState/useRef for nullable and mutable state

5. Generic Patterns (HIGH)

• generic-constrain-dont-overconstrain [blocked] — Constrain generics minimally
• generic-avoid-distributive-surprises [blocked] — Control distributive conditional types
• generic-mapped-type-utilities [blocked] — Build custom mapped types for repeated transformations
• generic-return-type-inference [blocked] — Preserve return type inference in generic functions

6. Compiler Performance (MEDIUM-HIGH)

• compile-explicit-return-types [blocked] — Add explicit return types to exported functions
• compile-avoid-deep-recursion [blocked] — Avoid deeply recursive type definitions
• compile-project-references [blocked] — Use project references for monorepo builds
• compile-base-types-over-unions [blocked] — Use base types instead of large union types
• compile-isolated-declarations [blocked] — Enable isolatedDeclarations for parallel declaration emit

7. Error Safety (MEDIUM)

• error-result-type [blocked] — Use Result types instead of thrown exceptions
• error-exhaustive-error-handling [blocked] — Use exhaustive checks for typed error variants
• error-typed-catch [blocked] — Type catch clause variables as unknown
• error-discriminated-error-unions [blocked] — Model domain errors as discriminated unions

8. Runtime Patterns (MEDIUM)

• perf-union-literals-over-enums [blocked] — Use union literals instead of enums — enums are non-erasable
• perf-avoid-delete-operator [blocked] — Avoid the delete operator on objects
• perf-object-freeze-const [blocked] — Use Object.freeze with as const for true immutability
• perf-object-keys-narrowing [blocked] — Avoid Object.keys type widening
• perf-map-set-over-object [blocked] — Use Map and Set over plain objects for dynamic collections

9. Quirks & Pitfalls (LOW-MEDIUM)

• quirk-excess-property-checks [blocked] — Understand excess property checks on object literals
• quirk-empty-object-type [blocked] — Avoid the {} type — it means non-nullish
• quirk-structural-typing-escapes [blocked] — Guard against structural typing escape hatches
• quirk-variance-annotations [blocked] — Use variance annotations to document generic intent (not for speed)

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions [blocked] — Category structure and impact levels
• Rule template [blocked] — Template for adding new rules

Reference Files