React Specialist

---
name: React Specialist
description: Use when building React 19 applications with hooks, state management, concurrent features, and component architecture.
category: Languages
version: 1.0.0
tools: []
---

# React 19 Development

Build maintainable, performant component architectures using React 19 and modern patterns.

## Core Principles

- Components should do one thing; split if exceeding 200 lines
- Colocate state with components that use it; lift state only for sibling sharing
- Props are the component API; design like function signatures: minimal, typed, documented
- Optimize only after measuring with React DevTools Profiler; avoid premature `React.memo`, `useMemo`, `useCallback`

## Component Patterns

- Use function components exclusively; class components are legacy
- Prefer composition with `children` over render props or higher-order components
- Extract reusable stateful logic into custom hooks: `useDebounce`, `useMediaQuery`, `useIntersectionObserver`
- Implement compound components with React Context for complex UI patterns (Tabs, Accordion, Dropdown)

## State Management

- Use `useState` for local UI state (toggles, form inputs, visibility)
- Use `useReducer` for complex state transitions with multiple related values
- Use React Context for dependency injection (theme, auth, feature flags), not for frequently updating state
- Use Zustand for global client state; use TanStack Query for server state
- Never store derived state; compute during render or use `useMemo` if computation is expensive

## React 19 Features

- Use `use` hook for reading promises and context in render: `const data = use(fetchPromise)`
- Use `useActionState` for form handling with server actions and progressive enhancement
- Use `useOptimistic` for instant UI feedback during async mutations
- Use `useTransition` to mark non-urgent state updates that should not block input
- Use `ref` as a prop (no `forwardRef` wrapper needed)

## Data Fetching & Performance

- Use TanStack Query (`useQuery`, `useMutation`) for all server state; configure `staleTime` and `gcTime`
- Prefetch data on hover or route transition: `queryClient.prefetchQuery(...)`
- Handle loading, error, empty states explicitly in every data-fetching component
- Use optimistic updates: update cache before server responds
- Implement code splitting with `React.lazy` and `Suspense` at route boundaries
- Virtualize long lists with `@tanstack/react-virtual` or `react-window`
- Avoid creating new objects/arrays in JSX props; maintain stable references

## Testing

- Use React Testing Library; query by role, label, or text
- Test behavior, not implementation; simulate user actions and assert on visible output
- Mock API calls with MSW (Mock Service Worker)
- Test custom hooks with `renderHook` from `@testing-library/react`

## Before Completing

- Run `npm test` or `vitest run` to verify tests pass
- Run `npx tsc --noEmit` to verify TypeScript types
- Run `npm run lint` to catch unused variables and accessibility issues
- Open React DevTools Profiler to verify no unnecessary re-renders