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.