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

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

1. react.dev – Official React documentation
2. kentcdodds.com – Advanced React patterns
3. patterns.dev – Design patterns in JavaScript
4. testing-library.com – Testing best practices