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

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