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

2. Type Narrowing & Guards (CRITICAL)

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

3. Modern TypeScript (HIGH)

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

4. React & TSX (HIGH)

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

5. Generic Patterns (HIGH)

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

6. Compiler Performance (MEDIUM-HIGH)

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

7. Error Safety (MEDIUM)

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

8. Runtime Patterns (MEDIUM)

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

9. Quirks & Pitfalls (LOW-MEDIUM)

• `quirk-excess-property-checks` — Understand excess property checks on object literals
• `quirk-empty-object-type` — Avoid the {} type — it means non-nullish
• `quirk-structural-typing-escapes` — Guard against structural typing escape hatches
• `quirk-variance-annotations` — 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 — Category structure and impact levels
• Rule template — Template for adding new rules

Reference Files