typescript-refactor

name

typescript-refactor

description

TypeScript and TSX refactoring and modernization guidelines from a principal specialist perspective, current to TypeScript 6.0 and React 19. This skill should be used when refactoring, reviewing, or modernizing TypeScript or React/TSX code for type safety, compiler performance, and idiomatic patterns. Triggers on tasks involving type architecture, narrowing, generics, discriminated unions, error handling, React component and hook typing, or migration to modern TypeScript features (satisfies, using, const type parameters, inferred type predicates, isolatedDeclarations, erasable syntax, import attributes).

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

Priority	Category	Impact	Prefix
1	Type Architecture	CRITICAL	arch-
2	Type Narrowing & Guards	CRITICAL	narrow-
3	Modern TypeScript	HIGH	modern-
4	React & TSX	HIGH	tsx-
5	Generic Patterns	HIGH	generic-
6	Compiler Performance	MEDIUM-HIGH	compile-
7	Error Safety	MEDIUM	error-
8	Runtime Patterns	MEDIUM	perf-
9	Quirks & Pitfalls	LOW-MEDIUM	quirk-

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

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information