modern-best-practice-react-components

name	modern-best-practice-react-components
description	Build clean, modern React components that apply common best practices and avoid common pitfalls like unnecessary state management or useEffect usage

Writing React Components

We're using modern React (19+) + React Compiler and we're following common best practices focused on clarity, correctness, and maintainability. Important to note, some components have incorrect architectural decisions and we'll rework them soon.

Component Structure & Style

• PREFER small, focused components with a single responsibility
• PREFER arrow function components over named functions
• PREFER explicit return types and props typing (TypeScript) where applicable
• Keep components flat and readable; avoid deeply nested JSX
• Group related logic together (event handlers, derived values, helpers)

State Management

• AVOID useEffect()
  • See the "You Might Not Need An Effect" guide for detailed guidance
  • PREFER deriving values during render instead of synchronizing state
  • Fetch data via TanStack Query (@tanstack/react-query)
• AVOID unnecessary useState() or useReducer() usage
  • Derive state from props or other state when possible
  • Localize state to the lowest possible component
• DO NOT mirror props in state unless absolutely necessary
• Prefer controlled components over syncing uncontrolled state

Rendering & Derivation

• PREFER computing derived values inline or via helper functions
• Use useMemo() sparingly and only for proven performance issues
• AVOID premature optimization
• Keep render logic deterministic and free of side effects

Event Handling

• AVOID in-line event handlers in JSX

  • PREFER:

    const handleClick = () => {
      // ...
    }
    
    <button onClick={handleClick} />;
    

  • Over:

    <button
      onClick={() => {
        /* ... */
      }}
    />
    

• Name handlers clearly (handleSubmit, handleChange, handleClose)

• Keep handlers small; extract complex logic into helpers

Effects, Data, and Side Effects

• AVOID effects for:
  • Derived state
  • Data transformations
  • Event-based logic that can live in handlers
• If side effects are unavoidable, keep them minimal, isolated, and well-documented
• Prefer framework-level or external abstractions (routers, data libraries) over raw effects

Props & Composition

• PREFER composition over configuration
• AVOID excessive boolean props; prefer expressive APIs
• Use children intentionally and document expected structure
• Keep prop names semantic and predictable

Performance & Stability

• PREFER stable references only when required (not by default)
• AVOID unnecessary memoization (memo, useCallback) unless absolutely required
• Keep keys stable and meaningful when rendering lists

General Principles

• Write code for humans first, compilers second
• Prefer explicitness over cleverness
• Optimize for readability and long-term maintenance
• If a pattern feels complex, reconsider the component boundary