Skip to content
Skills Library
Programming · Building & coding

typescript-refactor

/typescript-refactor

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 a

Repository
dot-skills ↗
Licence
MIT
Last repository change
15.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
52
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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 a

Original author 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 a

How it works

  1. When to Apply
  2. Rule Categories by Priority
  3. Quick Reference
  4. How to Use
  5. Reference Files
Original SKILL.md headings · 122 lines, 847 words
SKILL.md preview
---
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`](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 |
| [metadata.json](metadata.json) | Version and reference information |
Files in this package (52)
  • AGENTS.md 11 KB
  • SKILL.md 9 KB
  • metadata.json 1 KB
  • assets/templates/_template.md 1 KB
  • references/_sections.md 2 KB
  • references/arch-avoid-partial-abuse.md 1 KB
  • references/arch-branded-types.md 1 KB
  • references/arch-const-assertion.md 1 KB
  • references/arch-discriminated-unions.md 2 KB
  • references/arch-interfaces-over-intersections.md 2 KB
  • references/arch-readonly-by-default.md 1 KB
  • references/arch-satisfies-over-annotation.md 1 KB
  • references/compile-avoid-deep-recursion.md 1 KB
  • references/compile-base-types-over-unions.md 2 KB
  • references/compile-explicit-return-types.md 2 KB
  • references/compile-isolated-declarations.md 2 KB
  • references/compile-project-references.md 2 KB
  • references/error-discriminated-error-unions.md 1 KB
  • references/error-exhaustive-error-handling.md 1 KB
  • references/error-result-type.md 2 KB
  • references/error-typed-catch.md 1 KB
  • references/generic-avoid-distributive-surprises.md 1 KB
  • references/generic-constrain-dont-overconstrain.md 1 KB
  • references/generic-mapped-type-utilities.md 1 KB
  • references/generic-return-type-inference.md 1 KB
  • references/modern-const-type-parameters.md 1 KB
  • references/modern-erasable-syntax.md 2 KB
  • references/modern-import-attributes.md 1 KB
  • references/modern-noinfer-utility.md 1 KB
  • references/modern-template-literal-types.md 1 KB
  • references/modern-using-keyword.md 2 KB
  • references/modern-verbatim-module-syntax.md 1 KB
  • references/narrow-assertion-functions.md 2 KB
  • references/narrow-custom-type-guards.md 2 KB
  • references/narrow-eliminate-as-casts.md 2 KB
  • references/narrow-exhaustive-switch.md 2 KB
  • references/narrow-in-operator.md 2 KB
  • references/perf-avoid-delete-operator.md 1 KB
  • references/perf-map-set-over-object.md 2 KB
  • references/perf-object-freeze-const.md 1 KB
  • references/perf-object-keys-narrowing.md 2 KB
  • references/perf-union-literals-over-enums.md 2 KB
  • references/quirk-empty-object-type.md 1 KB
  • references/quirk-excess-property-checks.md 2 KB
  • references/quirk-structural-typing-escapes.md 1 KB
  • references/quirk-variance-annotations.md 2 KB
  • references/tsx-avoid-react-fc.md 1 KB
  • references/tsx-discriminated-props.md 2 KB
  • references/tsx-event-handler-types.md 1 KB
  • references/tsx-extend-native-props.md 2 KB
  • references/tsx-hook-typing.md 1 KB
  • references/tsx-ref-as-prop.md 1 KB

Versions

The database has no other skills named typescript-refactor.

Database snapshot: 13.11.2026 · package version 5d89fda318f0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95typescript-patterns
    TypeScript patterns for strict, type-safe, maintainable code in modern TypeScript and JavaScript applications. Covers strict compiler configuration, type design, narrowing, discriminated unions, generics, async and error handling, module boundaries, dependency hygiene, and…
  • 100typescript-type-safety
    TypeScript type safety patterns - unknown vs any, generics golden rule, null narrowing, inference discipline, import type, discriminated unions, error typing. Use when writing or reviewing TypeScript code for type correctness.
  • 95typescript-react-nextjs-patterns
    Production-grade TypeScript reference for React & Next.js frontend development. Covers type narrowing, component Props, generic hooks, discriminated unions, as const, satisfies, Zod validation, TanStack Query, server/client boundaries, forms, state management, performance,…
  • 100typescript-expert
    Expert TypeScript: type system, generics, narrowing, inference, and strict-mode safety. Trigger keywords: TypeScript, types, generics, type narrowing, tsconfig, strict, discriminated union, conditional/mapped types, utility types, declaration files, type error, satisfies, infer,…
  • 91typescript-best-practices
    TypeScript idioms and type-safety patterns: discriminated unions, branded types, narrowing, boundary validation. Use when reading, writing, or reviewing any .ts or .tsx file.
  • 95typescript-conventions
    Best practices and conventions for TypeScript and React development, covering type safety, interfaces, discriminated unions, strict mode, functional components, hooks, state management, CSS modules, and project tooling. Apply this skill whenever writing, reviewing, or…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.