React Core Team React Principles Best Practices
Comprehensive React development principles extracted from the official React documentation. Contains 52 rules across 8 categories prioritized by impact on code quality and maintainability.
When to Apply
Reference these guidelines when:
- •Writing React components with hooks
- •Managing component and application state
- •Synchronizing with external systems (APIs, browser APIs)
- •Debugging unexpected re-renders or stale state
- •Structuring state for complex UIs
- •Deciding between state, refs, context, and reducers
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Component Purity | HIGH | pure- |
| 2 | State Structure | HIGH | state- |
| 3 | State Sharing | HIGH | share- |
| 4 | Effect Patterns | HIGH | effect- |
| 5 | Refs Usage | MEDIUM | ref- |
| 6 | Reducer Patterns | MEDIUM | reducer- |
| 7 | Context Patterns | MEDIUM | context- |
| 8 | Event Handling | MEDIUM | event- |
Quick Reference
1. Component Purity (HIGH)
- •
pure-no-external-mutations- Never mutate external variables during render - •
pure-same-inputs-same-outputs- Same props/state always produce same JSX - •
pure-local-mutation-allowed- Local mutation during render is fine - •
pure-strict-mode-detection- Use StrictMode to catch purity violations - •
pure-side-effects-in-handlers- Put side effects in event handlers - •
pure-props-as-readonly- Treat props as immutable snapshots - •
pure-render-independence- Render order shouldn't matter - •
pure-use-effect-last-resort- Effects are escape hatches, not primary pattern - •
pure-why-purity-matters- Pure components enable React's features
2. State Structure (HIGH)
- •
state-group-related- Group related state variables together - •
state-avoid-contradictions- Avoid contradictory state (use enums) - •
state-avoid-redundant- Don't store values that can be derived - •
state-avoid-duplication- Store IDs, not duplicate objects - •
state-flatten-nested- Flatten deeply nested state - •
state-no-mirror-props- Don't initialize state from props - •
state-immutable-updates- Always create new objects/arrays - •
state-snapshot-behavior- State is a snapshot at render time - •
state-updater-functions- Use updaters for sequential updates - •
state-keys-reset- Use key to reset component state
3. State Sharing (HIGH)
- •
share-lift-state-up- Lift state to nearest common ancestor - •
share-single-source-truth- One source of truth for each piece - •
share-controlled-uncontrolled- Controlled vs uncontrolled patterns - •
share-props-down-events-up- Props flow down, events bubble up - •
share-composition-over-drilling- Use composition to avoid drilling - •
share-preserve-reset-identity- Component identity affects state
4. Effect Patterns (HIGH)
- •
effect-synchronization- Effects sync with external systems - •
effect-cleanup- Always provide cleanup functions - •
effect-dependencies- Include all dependencies in array - •
effect-separate-concerns- Separate independent synchronizations - •
effect-think-sync-not-lifecycle- Think sync/unsync, not mount/unmount - •
effect-not-for-derived-state- Don't use effects for derived state - •
effect-not-for-events- Don't use effects for event responses - •
effect-data-fetching- Proper patterns for data fetching - •
effect-never-suppress-linter- Never suppress dependency warnings - •
effect-remove-unnecessary- Remove effects that don't need to be effects
5. Refs Usage (MEDIUM)
- •
ref-escape-hatch- Refs are escape hatches from React - •
ref-no-render-access- Don't read/write refs during render - •
ref-dom-manipulation- Use refs for DOM manipulation - •
ref-mutable-values- Refs for mutable values like timers - •
ref-best-practices- When to use refs vs state
6. Reducer Patterns (MEDIUM)
- •
reducer-when-to-use- When to use reducers over useState - •
reducer-actions- Actions describe what happened - •
reducer-pure-functions- Reducers must be pure - •
reducer-structure- Standard reducer structure patterns - •
reducer-extract-from-component- Extract reducers to separate files
7. Context Patterns (MEDIUM)
- •
context-when-to-use- When to use context vs props - •
context-create-use-provide- Create, use, provide pattern - •
context-with-reducer- Combine context with reducers - •
context-default-values- Meaningful default values
8. Event Handling (MEDIUM)
- •
event-pass-handlers- Pass handlers, don't call them inline - •
event-side-effects- Side effects belong in handlers - •
event-propagation- Event propagation and stopPropagation - •
event-naming- Handler naming conventions (handle/on)
How to Use
Read individual reference files for detailed explanations and code examples:
- •Section definitions - Category structure and impact levels
- •Example rules: pure-no-external-mutations, effect-synchronization
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md