react-refactor

SKILL.md

React Refactor Best Practices

Architectural refactoring guide for React applications. Contains 40 rules across 7 categories, prioritized by impact from critical (component and state architecture) to incremental (refactoring safety).

When to Apply

Refactoring existing React codebases or planning large-scale restructuring

Reviewing PRs for architectural issues and code smells

Decomposing oversized components into focused units

Extracting reusable hooks from component logic

Improving testability of React code

Reducing coupling between feature modules

Rule Categories

Category
Impact
Rules
Key Topics

Component Architecture
CRITICAL
8
Compound components, headless pattern, composition over props, client boundaries

State Architecture
CRITICAL
7
Colocation, state machines, URL state, derived values

Hook Patterns
HIGH
6
Single responsibility, naming, dependency stability, composition

Component Decomposition
HIGH
6
Scroll test, extraction by change reason, view/logic separation

Coupling & Cohesion
MEDIUM
4
Dependency injection, circular deps, stable imports, barrel-free

Data & Side Effects
MEDIUM
4
Server-first fetch, TanStack Query, error boundaries

Refactoring Safety
LOW-MEDIUM
5
Characterization tests, behavior testing, integration tests

Quick Reference

Critical patterns — get these right first:

Use compound components instead of props explosion

Colocate state with the components that use it

Use state machines for complex UI workflows

Separate container logic from presentational components

Common mistakes — avoid these anti-patterns:

Lifting state to App when only one component reads it

Using context for rapidly-changing values

Monolithic hooks that fetch + transform + cache

Testing implementation details instead of behavior

Table of Contents

Component Architecture — CRITICAL

1.1 Apply Interface Segregation to Component Props — CRITICAL (prevents 30-50% of unnecessary re-renders)

1.2 Colocate Files by Feature Instead of Type — CRITICAL (reduces cross-directory navigation by 70%)

1.3 Convert Render Props to Custom Hooks — CRITICAL (eliminates 2-4 levels of nesting)

1.4 Extract Headless Components for Logic Reuse — CRITICAL (5x more reuse scenarios)

1.5 Prefer Composition Over Props Explosion — CRITICAL (reduces prop count by 50-70%)

1.6 Separate Container Logic from Presentational Components — CRITICAL (enables independent testing)

1.7 Use Compound Components for Implicit State Sharing — CRITICAL (reduces API surface by 60%)

1.8 Push Client Boundaries to Leaf Components — HIGH (keeps 60-80% server-rendered)

State Architecture — CRITICAL

2.1 Colocate State with Components That Use It — CRITICAL (reduces prop passing by 60%)

2.2 Derive Values Instead of Syncing State — CRITICAL (eliminates double-render cycle)

2.3 Lift State Only When Multiple Components Read It — CRITICAL (eliminates unnecessary parent re-renders)

2.4 Use Context for Rarely-Changing Values Only — CRITICAL (5-50x fewer re-renders)

2.5 Use State Machines for Complex UI Workflows — CRITICAL (reduces valid states from 2^n to N)

2.6 Use URL Parameters as State for Shareable Views — CRITICAL (enables deep linking and sharing)

2.7 Use useReducer for Multi-Field State Transitions — CRITICAL (eliminates impossible states)

Hook Patterns — HIGH

3.1 Avoid Object and Array Dependencies in Custom Hooks — HIGH (prevents effect re-execution every render)

3.2 Compose Hooks Instead of Nesting Them — HIGH (flattens dependency graph)

3.3 Extract Logic into Custom Hooks When Behavior Is Nameable — HIGH (40-60% shorter components)

3.4 Follow Hook Naming Conventions for Discoverability — HIGH (reduces navigation time by 40%)

3.5 Keep Custom Hooks to a Single Responsibility — HIGH (3x easier to test)

3.6 Stabilize Hook Dependencies with Refs and Callbacks — HIGH (prevents infinite loops)

Component Decomposition — HIGH

4.1 Apply the Scroll Test to Identify Oversized Components — HIGH (3x faster code review)

4.2 Complete Component Extraction Without Half-Measures — HIGH (enables independent testing and reuse)

4.3 Extract Components by Independent Change Reasons — HIGH (70% fewer files touched per change)

4.4 Extract Pure Functions from Component Bodies — HIGH (10x faster unit tests)

4.5 Inline Premature Abstractions Before Re-Extracting — HIGH (40-60% simpler code)

4.6 Separate View Layer from Business Logic — HIGH (5x faster test suite)

Coupling & Cohesion — MEDIUM

5.1 Break Circular Dependencies with Intermediate Modules — MEDIUM (eliminates undefined-at-import-time bugs)

5.2 Import from Stable Public API Surfaces Only — MEDIUM (enables internal refactoring)

5.3 Use Barrel-Free Feature Modules for Clean Dependencies — MEDIUM (200-800ms build reduction)

5.4 Use Dependency Injection for External Services — MEDIUM (3x faster test setup)

Data & Side Effects — MEDIUM

6.1 Fetch Data on the Server by Default — MEDIUM (reduces client JS by 30-60%)

6.2 Place Error Boundaries at Data Fetch Granularity — MEDIUM (errors isolated to affected section)

6.3 Use Context Module Pattern for Action Colocation — MEDIUM (centralizes data mutations)

6.4 Use TanStack Query for Client-Side Server State — MEDIUM (eliminates 80% of fetch boilerplate)

Refactoring Safety — LOW-MEDIUM

7.1 Avoid Snapshot Tests for Refactored Components — LOW-MEDIUM (eliminates false test failures)

7.2 Extract Pure Functions to Increase Testability — LOW-MEDIUM (10x faster test execution)

7.3 Prefer Integration Tests for Component Verification — LOW-MEDIUM (catches 40% more bugs)

7.4 Test Component Behavior Not Implementation Details — LOW-MEDIUM (5x fewer test updates)

7.5 Write Characterization Tests Before Refactoring — LOW-MEDIUM (catches 90% of unintended changes)

References

https://react.dev

https://react.dev/learn/thinking-in-react

https://kentcdodds.com/blog/application-state-management-with-react

https://testing-library.com/docs/guiding-principles

https://patterns.dev

Related Skills

For React 19 API best practices, see react skill

For application performance optimization, see react-optimise skill

For client-side form handling, see react-hook-form skill