react-principle-engineer（React principle 工程师）

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