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
reactskill - •For React core principles, see
react-principle-engineerskill - •For form handling, see
react-hook-formskill
References
- •react.dev - Official React documentation
- •kentcdodds.com - Advanced React patterns
- •patterns.dev - Design patterns in JavaScript
- •testing-library.com - Testing best practices