React Patterns

1---2name: react-patterns3description: Provides comprehensive React 19 patterns for Server Components, Server Actions, useOptimistic, useActionState, useTransition, concurrent features, Suspense boundaries, and TypeScript integration. Generates executable code patterns, validates security for public endpoints, and optimizes performance with React Compiler or manual memoization. Proactively use when building React 19 applications with Next.js App Router, implementing optimistic UI, or optimizing concurrent rendering.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob5---6 7# React 19 Development Patterns8 9## Overview10 11React 19 patterns for Next.js App Router, Server Actions, optimistic UI, and concurrent features. See Quick Reference for API summary and Examples for copy-paste patterns.12 13## When to Use14 15- Building React 19 applications with Next.js App Router16- Implementing optimistic UI with `useOptimistic` or `useTransition`17- Creating Server Actions with form validation18- Migrating from class components to hooks19- Optimizing concurrent rendering with React Compiler20- Managing complex state with `useReducer` or custom hooks21- Wrapping async operations in Suspense boundaries22 23## Quick Reference24 25| Pattern | Hook / API | Use Case |26|---------|-----------|----------|27| Local state | `useState` | Simple component state |28| Complex state | `useReducer` | Multi-action state machines |29| Side effects | `useEffect` | Subscriptions, data fetching |30| Shared state | `useContext` / `createContext` | Cross-component data |31| DOM access | `useRef` | Focus, measurements, timers |32| Performance | `useMemo` / `useCallback` | Expensive computations |33| Non-urgent updates | `useTransition` | Search/filter on large lists |34| Defer expensive UI | `useDeferredValue` | Stale-while-updating |35| Read resources | `use()` (React 19) | Promises and context in render |36| Optimistic UI | `useOptimistic` (React 19) | Instant feedback on mutations |37| Form status | `useFormStatus` (React 19) | Pending state in child components |38| Form state | `useActionState` (React 19) | Server action results |39| Auto-memoization | React Compiler | Eliminates manual memo/callback |40 41## Instructions42 431. **Identify Component Type**: Determine if Server Component or Client Component is needed442. **Select Hooks**: Use appropriate hooks for state management and side effects453. **Type Props**: Define TypeScript interfaces for all component props464. **Handle Async**: Wrap data-fetching components in Suspense boundaries475. **Optimize**: Use React Compiler or manual memoization for expensive renders486. **Handle Errors**: Add ErrorBoundary for graceful error handling497. **Validate Server Actions**: Define Zod/schema validation, then test:50   - Submit invalid inputs → verify rejection51   - Submit valid inputs → verify success52 53## Examples54 55### Server Component with Client Interaction56 57```tsx58// Server Component (default) — async, fetches data59async function ProductPage({ id }: { id: string }) {60  const product = await db.product.findUnique({ where: { id } });61 62  return (63    <div>64      <h1>{product.name}</h1>65      <AddToCartButton productId={product.id} />66    </div>67  );68}69 70// Client Component — handles interactivity71'use client';72function AddToCartButton({ productId }: { productId: string }) {73  const [isPending, startTransition] = useTransition();74 75  const handleAdd = () => {76    startTransition(async () => {77      await addToCart(productId);78    });79  };80 81  return (82    <button onClick={handleAdd} disabled={isPending}>83      {isPending ? 'Adding...' : 'Add to Cart'}84    </button>85  );86}87```88 89### useOptimistic for Instant Feedback90 91```tsx92'use client';93import { useOptimistic } from 'react';94 95function TodoList({ todos, addTodo }: { todos: Todo[]; addTodo: (t: Todo) => Promise<void> }) {96  const [optimisticTodos, addOptimisticTodo] = useOptimistic(97    todos,98    (state, newTodo: Todo) => [...state, { ...newTodo, pending: true }]99  );100 101  const handleSubmit = async (formData: FormData) => {102    const newTodo = { id: Date.now(), text: formData.get('text') as string };103    addOptimisticTodo(newTodo);  // Immediate UI update104    await addTodo(newTodo);      // Actual backend call105  };106 107  return (108    <form action={handleSubmit}>109      {optimisticTodos.map(todo => (110        <div key={todo.id} style={{ opacity: todo.pending ? 0.5 : 1 }}>111          {todo.text}112        </div>113      ))}114      <input type="text" name="text" />115      <button type="submit">Add</button>116    </form>117  );118}119```120 121### Server Action with Form122 123```tsx124// app/actions.ts125'use server';126import { z } from 'zod';127import { revalidatePath } from 'next/cache';128 129const schema = z.object({130  title: z.string().min(5),131  content: z.string().min(10),132});133 134export async function createPost(prevState: any, formData: FormData) {135  const parsed = schema.safeParse({136    title: formData.get('title'),137    content: formData.get('content'),138  });139 140  if (!parsed.success) {141    return { errors: parsed.error.flatten().fieldErrors };142  }143 144  await db.post.create({ data: parsed.data });145  revalidatePath('/posts');146  return { success: true };147}148 149// app/blog/new/page.tsx150'use client';151import { useActionState } from 'react';152import { createPost } from '../actions';153 154export default function NewPostPage() {155  const [state, formAction, pending] = useActionState(createPost, {});156 157  return (158    <form action={formAction}>159      <input name="title" placeholder="Title" />160      {state.errors?.title && <span>{state.errors.title[0]}</span>}161      <textarea name="content" placeholder="Content" />162      <button type="submit" disabled={pending}>163        {pending ? 'Publishing...' : 'Publish'}164      </button>165    </form>166  );167}168```169 170### Custom Hook171 172```tsx173export function useOnlineStatus() {174  const [isOnline, setIsOnline] = useState(true);175 176  useEffect(() => {177    function handleOnline() { setIsOnline(true); }178    function handleOffline() { setIsOnline(false); }179 180    window.addEventListener('online', handleOnline);181    window.addEventListener('offline', handleOffline);182 183    return () => {184      window.removeEventListener('online', handleOnline);185      window.removeEventListener('offline', handleOffline);186    };187  }, []);188 189  return isOnline;190}191```192 193### useTransition for Non-Urgent Updates194 195```tsx196function SearchableList({ items }: { items: Item[] }) {197  const [query, setQuery] = useState('');198  const [isPending, startTransition] = useTransition();199  const [filteredItems, setFilteredItems] = useState(items);200 201  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {202    setQuery(e.target.value);203    startTransition(() => {204      setFilteredItems(items.filter(i => i.name.toLowerCase().includes(e.target.value.toLowerCase())));205    });206  };207 208  return (209    <div>210      <input value={query} onChange={handleChange} />211      {isPending && <span>Filtering...</span>}212      <ul>{filteredItems.map(i => <li key={i.id}>{i.name}</li>)}</ul>213    </div>214  );215}216```217 218## Best Practices219 220### Server vs Client Decision221 222- Start with Server Component (no directive needed)223- Add `'use client'` only for: hooks, browser APIs, event handlers224 225### State Management226 227- Keep state minimal — compute derived values during render, not in effects228- Use `useReducer` for state with multiple related actions229- Lift state up to the nearest common ancestor230 231### Effects232 233- Use effects only for external system synchronization234- Always specify correct dependency arrays235- Return cleanup functions for subscriptions and timers236- Never mutate state directly — always create new references237 238### Performance239 240- With React Compiler: avoid manual `useMemo`, `useCallback`, `memo`241- Without React Compiler: use `useMemo` for expensive computations, `useCallback` for stable callbacks242- Use `useTransition` for low-priority state updates243- Use stable IDs as list keys, not array indices244 245### React 19 Specifics246 247- Wrap `use(promise)` components in Suspense boundaries248- Use `useActionState` for form-server action integration249- Validate Server Action inputs — they are public endpoints250- Pass serializable data from Server to Client Components251 252## Constraints and Warnings253 254- **Server Components**: Cannot use hooks, event handlers, or browser APIs255- **use() Hook**: Can only be called during render, not in callbacks or effects256- **Server Actions**: Must include `'use server'` directive; always validate inputs257- **State Mutations**: Never mutate state directly — always create new references258- **Effect Dependencies**: Include all dependencies in `useEffect` dependency arrays259- **Memory Leaks**: Always clean up subscriptions and event listeners in useEffect return260 261## References262 263Consult these files for detailed patterns:264 265- **[references/hooks-patterns.md](references/hooks-patterns.md)** — useState, useEffect, useRef, useReducer, custom hooks, common pitfalls266- **[references/component-patterns.md](references/component-patterns.md)** — Props, composition, lifting state, context, compound components, error boundaries267- **[references/react19-features.md](references/react19-features.md)** — use(), useOptimistic, useFormStatus, useActionState, Server Actions, Server Components, migration guide268- **[references/performance-patterns.md](references/performance-patterns.md)** — React Compiler setup, useMemo, useCallback, useTransition, useDeferredValue, lazy loading269- **[references/typescript-patterns.md](references/typescript-patterns.md)** — Typed props, generic components, event handlers, discriminated unions, context typing270- **[references/learn.md](references/learn.md)** — Progressive learning guide from basics to advanced React 19271- **[references/reference.md](references/reference.md)** — Complete API reference for all React hooks and component APIs