react-refactor

name

react-refactor

description

Architectural refactoring guide for React applications covering component architecture, state architecture, hook patterns, component decomposition, coupling and cohesion, data flow, and refactoring safety. Use when refactoring React codebases, reviewing PRs for architectural issues, decomposing oversized components, or improving module boundaries. Does NOT cover React 19 API usage (see react skill) or performance optimization (see react-optimise skill).

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

1. 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)
2. 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)
3. Hook Patterns — HIGH
   • 3.1 Avoid Object and Array Dependencies in Custom Hooks — HIGH (prevents effect re-execution every render)

References

1. https://react.dev
2. https://react.dev/learn/thinking-in-react
3. https://kentcdodds.com/blog/application-state-management-with-react
4. https://testing-library.com/docs/guiding-principles
5. 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