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 renderpure-same-inputs-same-outputs- Same props/state always produce same JSXpure-local-mutation-allowed- Local mutation during render is finepure-strict-mode-detection- Use StrictMode to catch purity violationspure-side-effects-in-handlers- Put side effects in event handlerspure-props-as-readonly- Treat props as immutable snapshotspure-render-independence- Render order shouldn't matterpure-use-effect-last-resort- Effects are escape hatches, not primary patternpure-why-purity-matters- Pure components enable React's features
2. State Structure (HIGH)
state-group-related- Group related state variables togetherstate-avoid-contradictions- Avoid contradictory state (use enums)state-avoid-redundant- Don't store values that can be derivedstate-avoid-duplication- Store IDs, not duplicate objectsstate-flatten-nested- Flatten deeply nested statestate-no-mirror-props- Don't initialize state from propsstate-immutable-updates- Always create new objects/arraysstate-snapshot-behavior- State is a snapshot at render timestate-updater-functions- Use updaters for sequential updatesstate-keys-reset- Use key to reset component state
3. State Sharing (HIGH)
share-lift-state-up- Lift state to nearest common ancestorshare-single-source-truth- One source of truth for each pieceshare-controlled-uncontrolled- Controlled vs uncontrolled patternsshare-props-down-events-up- Props flow down, events bubble upshare-composition-over-drilling- Use composition to avoid drillingshare-preserve-reset-identity- Component identity affects state
4. Effect Patterns (HIGH)
effect-synchronization- Effects sync with external systemseffect-cleanup- Always provide cleanup functionseffect-dependencies- Include all dependencies in arrayeffect-separate-concerns- Separate independent synchronizationseffect-think-sync-not-lifecycle- Think sync/unsync, not mount/unmounteffect-not-for-derived-state- Don't use effects for derived stateeffect-not-for-events- Don't use effects for event responseseffect-data-fetching- Proper patterns for data fetchingeffect-never-suppress-linter- Never suppress dependency warningseffect-remove-unnecessary- Remove effects that don't need to be effects
5. Refs Usage (MEDIUM)
ref-escape-hatch- Refs are escape hatches from Reactref-no-render-access- Don't read/write refs during renderref-dom-manipulation- Use refs for DOM manipulationref-mutable-values- Refs for mutable values like timersref-best-practices- When to use refs vs state
6. Reducer Patterns (MEDIUM)
reducer-when-to-use- When to use reducers over useStatereducer-actions- Actions describe what happenedreducer-pure-functions- Reducers must be purereducer-structure- Standard reducer structure patternsreducer-extract-from-component- Extract reducers to separate files
7. Context Patterns (MEDIUM)
context-when-to-use- When to use context vs propscontext-create-use-provide- Create, use, provide patterncontext-with-reducer- Combine context with reducerscontext-default-values- Meaningful default values
8. Event Handling (MEDIUM)
event-pass-handlers- Pass handlers, don't call them inlineevent-side-effects- Side effects belong in handlersevent-propagation- Event propagation and stopPropagationevent-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