React Best Practices

Production-grade React development with feature-based architecture, type-safe state management, and performance optimization.

Core Principles

Easy to get started with - Clear patterns that new team members can follow
Simple to understand and maintain - Readable code with obvious intent
Clean boundaries - Clear separation between features and layers
Early issue detection - Catch problems at build time, not runtime
Consistency - Same patterns throughout the codebase

Quick Reference

Topic	Guide
Directory layout and feature modules	project-structure.md
Component design patterns	component-patterns.md
Compound components (Card pattern)	compound-components.md
State categories and solutions	state-management.md
API client and request structure	api-layer.md
Code splitting and optimization	performance.md
useEffect guidance and alternatives	useeffect.md
Testing pyramid and strategy	testing-strategy.md
Project tooling standards	project-standards.md

When to Use Each Guide

Project Structure

Use project-structure.md when you need:

Directory organization (app, features, components)
Feature module structure
Import architecture (unidirectional flow)
ESLint boundary enforcement
File naming conventions

Component Patterns

Use component-patterns.md when you need:

Colocation principles
Composition over props patterns
Wrapping third-party components
Avoiding nested render functions

Compound Components

Use compound-components.md when you need:

Multi-part components (Card, Accordion, etc.)
Flexible composition patterns
Semantic component structure

State Management

Use state-management.md when you need:

State category decisions (component, application, server cache)
useState vs useReducer guidance
Server cache with React Query
State placement guidelines

API Layer

Use api-layer.md when you need:

API client configuration
Request structure (schema, fetcher, hook)
Error handling (interceptors, boundaries)
Security patterns (auth, sanitization, authorization)

Performance

Use performance.md when you need:

Code splitting strategies
State optimization
Children optimization patterns
Styling performance
Image optimization

useEffect

Use useeffect.md when you need:

When NOT to use useEffect (most cases)
When useEffect IS appropriate (external systems)
Dependency array rules
Alternatives to useEffect

Testing Strategy

Use testing-strategy.md when you need:

Testing pyramid (prioritize integration over unit)
What to test at each level (unit, integration, E2E)
Testing Library principles (query by accessible names)

Project Standards

Use project-standards.md when you need:

Required tooling (ESLint, Prettier, TypeScript, Husky)
Pre-commit hook configuration

Quick Reference: Decision Trees

Where should this component live?

Is it used by multiple features?
├── Yes → src/components/
└── No → Is it specific to one feature?
    ├── Yes → src/features/[feature]/components/
    └── No → Colocate with the component that uses it

What state solution should I use?

Is this data from an API?
├── Yes → React Query / SWR
└── No → Is it form data?
    ├── Yes → React Hook Form
    └── No → Is it URL state (filters, pagination)?
        ├── Yes → React Router
        └── No → Is it needed globally?
            ├── Yes → Zustand / Jotai / Context
            └── No → useState / useReducer

Should I create a new feature folder?

Does this functionality have:
- Its own routes/pages?
- Its own API endpoints?
- Components not shared elsewhere?
├── Yes to 2+ → Create feature folder
└── Otherwise → Add to existing feature or shared

Do I need useEffect?

Why does this code need to run?

"Because the component was displayed"
├── Is it synchronizing with an external system?
│   ├── Yes → useEffect is appropriate
│   └── No → Probably don't need useEffect
│
"Because the user did something"
└── Put it in the event handler, not useEffect

"Because I need to compute a value"
└── Calculate during render (or useMemo if expensive)

See useeffect.md for detailed guidance.

react