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