React Guidelines

This document outlines best practices for building robust, maintainable, and modern React applications with TypeScript.

1. General Principles

Component Composition: Build small, focused components and compose them to build complex UIs.
Unidirectional Data Flow: Data flows down (props), actions flow up (callbacks).
Immutability: Treat state as immutable. Use functional updates and immutable patterns.
Colocation: Keep related logic, styles, and tests close to the component.

2. TypeScript Integration

Strict Typing: Always use strict: true in tsconfig.json. avoiding any ensures type safety.

Props Interfaces: Define explicit interfaces for component props.

interface ButtonProps {
    label: string;
    onClick: () => void;
    variant?: 'primary' | 'secondary';
}

Discriminated Unions: Use discriminated unions for state that can be in distinct modes (e.g., handling loading/success/error states).

type State = 
    | { status: 'idle' }
    | { status: 'loading' }
    | { status: 'success'; data: User }
    | { status: 'error'; error: Error };

Event Types: Use React's built-in event types (e.g., React.ChangeEvent<HTMLInputElement>, React.FormEvent).

3. State Management Best Practices

Derived State (Crucial)

Avoid Redundant State: Do not store state that can be calculated from existing props or other state.

Calculate on Render: Compute values directly in the component body.

Bad:

const [filteredList, setFilteredList] = useState([]);

// This is an anti-pattern: syncing state
useEffect(() => {
    setFilteredList(items.filter(i => i.active));
}, [items]);

Good:

// Calculated during render. Always fresh, no sync bugs.
const filteredList = items.filter(i => i.active);

Memoization: Use useMemo only if the calculation is computationally expensive.

useState vs useReducer

Use useState for simple, independent values.
Use useReducer for complex state logic, or when the next state depends on the previous one in complex ways.

4. useEffect Usage and Pitfalls

Synchronization, Not Data Flow: useEffect is for synchronizing with external systems (APIs, DOM, subscriptions). It is not for transforming data or "watching" props to update state.
Fetching Data: When fetching data, handle race conditions (e.g., ignore results if the component unmounts or the query changes).
Strict Dependencies: Always include all variables used in the effect in the dependency array.
Cleanup Functions: Always return a cleanup function for effects that create subscriptions or event listeners.

5. Component Patterns

Custom Hooks: Extract logic into custom hooks (useUser, useWindowSize). This keeps components focused on UI.
Container/Presentational: While strictly rigidly separating them is less common now, separating logically complex data-fetching components from pure UI components is still good practice.
Fragments: Use <> (Fragments) to avoid unnecessary DOM wrapper nodes.

6. Performance

Stable Identity: Wrap functions passed as props in useCallback only if the child component is wrapped in React.memo or if the function is a dependency of minimal effect.
Lists: Always use a unique, stable key for list items. Do not use array index.
Lazy Loading: Use React.lazy and Suspense for route-level code splitting.

react-guidelines