react-conventions

React / TypeScript Frontend Conventions

Stack Defaults

Layer	Technology
Runtime	React 18+
Language	TypeScript (strict)
Styling	Tailwind CSS
Data Fetching	TanStack Query
Forms	React Hook Form + Zod
Routing	React Router v7
State	Zustand (global client), React context (theme/auth)
Testing	Vitest + React Testing Library
Build	Vite or Next.js
Package Manager	pnpm

Component Design

• Functional components only; composition over configuration
• Extend native HTML props where appropriate (React.ButtonHTMLAttributes<HTMLButtonElement>)
• Use discriminated props for variants (variant: 'primary' | 'secondary') — avoid boolean prop proliferation
• Prefer compound components: <Card><CardHeader /><CardContent /></Card> over <Card title="..." />
• Forward refs when wrapping native elements (input, button) for form/focus libraries
• children: React.ReactNode for flexible content

State Management Decision Tree

1. Single component → useState (or useReducer for complex transitions)
2. 2-3 siblings → Lift state or useContext
3. Server data → TanStack Query (NOT Zustand)
4. Global client state → Zustand (or context for theme/auth)

Never store server data in Zustand. TanStack Query handles caching, refetching, and invalidation.

Zustand

• Focused stores; use selectors to avoid re-renders: useStore(s => s.field)
• persist middleware only when needed (preferences)
• Async: call set after await, not inside store creation

Derived State

• Compute in render (useMemo if expensive) — don't store derivable values

Data Fetching (TanStack Query)

• useQuery: queryKey includes all dependencies (filters, pagination, id)
• useMutation: onSuccess → queryClient.invalidateQueries()
• Optimistic updates: onMutate → set cache, onError → rollback, onSettled → invalidate
• Use isLoading for initial load, isFetching for background refetch
• Prefetch on hover/intent: queryClient.prefetchQuery()
• Never fetch in useEffect for server data — use useQuery or route loader

Forms (React Hook Form + Zod)

• useForm<T>({ resolver: zodResolver(schema), defaultValues })
• Infer type: type FormData = z.infer<typeof schema>
• Inline field errors: formState.errors.field?.message with aria-invalid
• Disable submit during submission: disabled={isSubmitting}
• API errors: setError('fieldName', { message }) or setError('root', { message })
• Use useMutation (TanStack Query) with mutateAsync in onSubmit

Error Boundaries

• Place around route segments or features — one failure should not take down the whole app
• Granular boundaries: app-level → sidebar → main content → individual widgets
• Provide fallback UI with retry button
• Log errors in componentDidCatch callback

Testing

• Vitest + React Testing Library (RTL)
• Test behavior and user experience, not implementation details
• Query priority: getByRole > getByLabelText > getByText > getByTestId (last resort)
• Async: findBy* or waitFor(() => expect(...))
• User actions via userEvent (click, type), not fireEvent
• Mock API with MSW or vi.mock on API module
• Test naming: should {expected} when {condition}
• One behavior per test

Performance

• Measure first — optimize only with evidence (React DevTools Profiler)
• React.memo: only for expensive components with stable props
• useMemo: only for expensive computations with correct deps
• useCallback: only when passing stable callback to memoized child
• Code splitting: lazy(() => import('./Page')) + <Suspense> for routes and heavy components
• Do NOT memo/useMemo/useCallback everything — it adds overhead when unnecessary

Accessibility

• Semantic HTML elements first, ARIA attributes when needed
• Keyboard navigation for all interactive elements
• Focus management on route changes and modals
• aria-invalid, aria-describedby for form errors

Anti-Patterns

• Server data in Zustand (use TanStack Query)
• Prop drilling (use context, composition, or Zustand)
• Testing implementation details (internal state, method calls)
• getByTestId as first choice (use accessible queries)
• memo/useMemo/useCallback everywhere without measurement
• Inline object/function props on memoized components
• Storing derivable values in state
• Fetch in useEffect for server data

Additional Resources

For detailed patterns, consult:

• references/patterns.md — Compound components, TanStack Query advanced, form patterns, code splitting, Tailwind design tokens