typescript-refactor

Files (52)

• AGENTS.md
• SKILL.md
• _template.md · assets/templates/
• metadata.json
• _sections.md · references/
• arch-avoid-partial-abuse.md · references/
• arch-branded-types.md · references/
• arch-const-assertion.md · references/
• arch-discriminated-unions.md · references/
• arch-interfaces-over-intersections.md · references/
• arch-readonly-by-default.md · references/
• arch-satisfies-over-annotation.md · references/
• compile-avoid-deep-recursion.md · references/
• compile-base-types-over-unions.md · references/
• compile-explicit-return-types.md · references/
• compile-isolated-declarations.md · references/
• compile-project-references.md · references/
• error-discriminated-error-unions.md · references/
• error-exhaustive-error-handling.md · references/
• error-result-type.md · references/
• error-typed-catch.md · references/
• generic-avoid-distributive-surprises.md · references/
• generic-constrain-dont-overconstrain.md · references/
• generic-mapped-type-utilities.md · references/
• generic-return-type-inference.md · references/
• modern-const-type-parameters.md · references/
• modern-erasable-syntax.md · references/
• modern-import-attributes.md · references/
• modern-noinfer-utility.md · references/
• modern-template-literal-types.md · references/
• modern-using-keyword.md · references/
• modern-verbatim-module-syntax.md · references/
• narrow-assertion-functions.md · references/
• narrow-custom-type-guards.md · references/
• narrow-eliminate-as-casts.md · references/
• narrow-exhaustive-switch.md · references/
• narrow-in-operator.md · references/
• perf-avoid-delete-operator.md · references/
• perf-map-set-over-object.md · references/
• perf-object-freeze-const.md · references/
• perf-object-keys-narrowing.md · references/
• perf-union-literals-over-enums.md · references/
• quirk-empty-object-type.md · references/
• quirk-excess-property-checks.md · references/
• quirk-structural-typing-escapes.md · references/
• quirk-variance-annotations.md · references/
• tsx-avoid-react-fc.md · references/
• tsx-discriminated-props.md · references/
• tsx-event-handler-types.md · references/
• tsx-extend-native-props.md · references/
• tsx-hook-typing.md · references/
• tsx-ref-as-prop.md · references/

SKILL.md (first lines)

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

### 2. Type Narrowing & Guards (CRITICAL)

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

### 3. Modern TypeScript (HIGH)

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

### 4. React & TSX (HIGH)

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

### 5. Generic Patterns (HIGH)

- [`generic-constrain-dont-overconstrain`](references/generic-constrain-dont-overconstrain.md) — Constrain generics minimally
- [`generic-avoid-distributive-surprises`](references/generic-avoid-distributive-surprises.md) — Control distributive conditional types
- [`generic-mapped-type-utilities`](references/generic-mapped-type-utilities.md) — Build custom mapped types for repeated transformations
- [`generic-return-type-inference`](references/generic-return-type-inference.md) — Preserve return type inference in generic functions

### 6. Compiler Performance (MEDIUM-HIGH)

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

### 7. Error Safety (MEDIUM)

- [`error-result-type`](references/error-result-type.md) — Use Result types instead of thrown exceptions
- [`error-exhaustive-error-handling`](references/error-exhaustive-error-handling.md) — Use exhaustive checks for typed error variants
- [`error-typed-catch`](references/error-typed-catch.md) — Type catch clause variables as `unknown`
- [`error-discriminated-error-unions`](references/error-discriminated-error-unions.md) — Model domain errors as discriminated unions

### 8. Runtime Patterns (MEDIUM)

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

### 9. Quirks & Pitfalls (LOW-MEDIUM)

- [`quirk-excess-property-checks`](references/quirk-excess-property-checks.md) — Understand excess property checks on object literals
- [`quirk-empty-object-type`](references/quirk-empty-object-type.md) — Avoid the `{}` type — it means non-nullish
- [`quirk-structural-typing-escapes`](references/quirk-structural-typing-escapes.md) — Guard against structural typing escape hatches
- [`quirk-variance-annotations`](references/quirk-variance-annotations.md) — 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](references/_sections.md) — Category structure and impact levels
- [Rule template](assets/templates/_template.md) — Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |

From pproenca/dot-skills, MIT.

More from pproenca/dot-skills