Principal Engineering React Best Practices

Principal-engineer-level refactoring guide for React applications. Contains 42 rules across 8 categories, prioritized by impact from critical (state architecture, composition) to incremental (testability). Each rule includes code smell indicators, before/after examples, and safe transformation steps.

When to Apply

Reference these guidelines when:

• Refactoring existing React codebases

• Reviewing PRs for architectural issues

• Identifying technical debt

• Planning large-scale refactoring efforts

• Deciding whether to extract, inline, or restructure components

• Improving testability of React code

Rule Categories by Priority

Priority Category Impact Prefix

1 State Architecture CRITICAL state-

2 Component Composition CRITICAL comp-

3 Abstraction Quality HIGH abs-

4 Coupling & Cohesion HIGH couple-

5 Hook Hygiene MEDIUM-HIGH hook-

6 Render Patterns MEDIUM render-

7 Side Effect Management MEDIUM effect-

8 Testability LOW-MEDIUM test-

Quick Reference

1. State Architecture (CRITICAL)

• state-prop-drilling-compound

• Replace prop drilling with compound components

• state-prop-drilling-composition

• Replace prop drilling with component composition

• state-derived-calculation

• Replace synchronized state with derived calculations

• state-machine-complex

• Replace boolean explosion with state machines

• state-colocation

• Colocate state with components that use it

• state-reducer-consolidation

• Consolidate related useState calls into useReducer

• state-context-selector

• Use context selectors to prevent cascade re-renders

• state-url-sync

• Move shareable state to URL parameters

2. Component Composition (CRITICAL)

• comp-render-props-extraction

• Extract shared logic with render props or hooks

• comp-slots-over-props

• Use slots/children instead of configuration props

• comp-god-component-split

• Split god components by responsibility

• comp-controlled-uncontrolled

• Choose controlled vs uncontrolled deliberately

• comp-headless-extraction

• Extract headless components for reusable behavior

• comp-props-spreading

• Avoid untyped props spreading

• comp-polymorphic-as

• Use polymorphic 'as' prop for flexible elements

• comp-children-validation

• Validate compound component children

3. Abstraction Quality (HIGH)

• abs-premature-abstraction

• Resist premature abstraction (Rule of Three)

• abs-over-configuration

• Prefer composition over configuration

• abs-extract-custom-hook

• Extract custom hooks for reusable logic

• abs-inline-vs-extract

• Know when to inline vs extract components

• abs-wrong-abstraction-fix

• Fix wrong abstractions by inlining first

• abs-utility-vs-domain

• Separate utility hooks from domain hooks

4. Coupling & Cohesion (HIGH)

• couple-colocation-files

• Colocate related files by feature

• couple-dependency-injection

• Use dependency injection for external services

• couple-interface-segregation

• Apply interface segregation to props

• couple-circular-deps

• Break circular dependencies with inversion

• couple-stable-imports

• Import from stable public APIs only

5. Hook Hygiene (MEDIUM-HIGH)

• hook-dependency-stability

• Ensure hook dependencies are stable

• hook-composition-over-size

• Compose small hooks rather than one large hook

• hook-return-object-vs-tuple

• Choose hook return type by use case

• hook-conditional-usage

• Never call hooks conditionally

• hook-naming-conventions

• Follow hook naming conventions

6. Render Patterns (MEDIUM)

• render-conditional-early-return

• Use early returns for conditional rendering

• render-list-key-stability

• Use stable, unique keys for lists

• render-avoid-inline-objects

• Avoid inline objects in JSX props

• render-fragment-cleanup

• Use fragments to avoid wrapper divs

7. Side Effect Management (MEDIUM)

• effect-to-event-handler

• Move event responses from effects to handlers

• effect-cleanup-required

• Always clean up effect side effects

• effect-single-responsibility

• Separate unrelated effects

• effect-avoid-unnecessary

• Remove effects that aren't synchronization

8. Testability (LOW-MEDIUM)

• test-seam-creation

• Create seams for testable components

• test-behavior-over-implementation

• Test behavior, not implementation details

• test-extract-for-testability

• Extract logic to hooks for testability

• test-mock-boundaries

• Mock at boundaries, not internal details

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

Related Skills

• For React 19 API best practices, see react skill

• For React core principles, see react-principle-engineer skill

• For form handling, see react-hook-form skill

References

• react.dev - Official React documentation

• kentcdodds.com - Advanced React patterns

• patterns.dev - Design patterns in JavaScript

• testing-library.com - Testing best practices