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

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