React Frontend

1. Server State: React Query (caching, sync, staleTime: 5min, gcTime: 10min)
2. URL State: useSearchParams, useRouter.push (filters, pagination, sorting)
3. Form State: React Hook Form + Zod (local form handling)
4. UI State: Zustand with subscribeWithSelector middleware (modals, dropdowns, UI toggles)

Core Patterns

Error Boundaries Per Route

Create error.tsx in each route segment. Catch and display errors for that segment only.

'use client'
export default function Error({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <div className="error-container">
      <h2>Something went wrong</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

Suspense Boundaries

Wrap data-fetching components in Suspense. Provide skeleton fallback UI.

<Suspense fallback={<StoreSkeleton />}>
  <StoreList />
</Suspense>

React Query for Server State

Fetch data with React Query. Cache automatically with staleTime: 5min, gcTime: 10min.

const { data, isLoading, error } = useQuery({
  queryKey: ['stores', tenantId],
  queryFn: () => api.stores.list(tenantId),
  staleTime: 5 * 60 * 1000,
  gcTime: 10 * 60 * 1000,
})

Mutate with optimistic updates using useOptimistic hook:

const [optimisticStores, addOptimistic] = useOptimistic(stores, (state, newStore) => [
  ...state,
  newStore,
])

const { mutate: createStore } = useMutation({
  mutationFn: (store) => api.stores.create(store),
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['stores'] }),
})

Zustand for UI State

Store UI state in Zustand with subscribeWithSelector for performance.

export const useUIStore = create<UIState>()((set) => ({
  isModalOpen: false,
  setModalOpen: (open) => set({ isModalOpen: open }),
}))

Form State with React Hook Form + Zod

Use zodResolver for validation.

const { register, handleSubmit, formState: { errors } } = useForm({
  resolver: zodResolver(createStoreSchema),
})

Performance Optimization

React.memo for expensive components that receive stable props.

useMemo for heavy calculations: useMemo(() => expensiveCalc(data), [data])

useCallback only for passing to memoized children, not for handlers.

Code Splitting: Use dynamic imports with Suspense fallback.

Image Optimization: Next.js Image component with quality: 75, placeholder blur.

Virtual Scrolling for large lists: useVirtualizer from @tanstack/react-virtual.

Bundle Analysis: Run ANALYZE=true next build to check bundle size.

Testing Strategy

• Unit: Vitest + React Testing Library for component logic
• Integration: MSW (Mock Service Worker) for API mocking
• E2E: Playwright for user flows
• Accessibility: axe-core for WCAG compliance

Security & Multi-tenancy

Multi-tenant Isolation: Use useTenant() hook to get current tenant from auth context.

Role-Based Access: RoleGate component checks user role before rendering.

CSRF Protection: Verify CSRF token from httpOnly cookies.

Environment Variables: Validate PUBLIC_* vars exist at build time.

QA Gate Checklist

ARCHITECTURE:
  □ Server Components used by default
  □ Client Components only where necessary
  □ error.tsx in each route segment
  □ Suspense boundaries around data fetches
  □ Layout.tsx properly structured

STATE MANAGEMENT:
  □ React Query for all server state
  □ staleTime: 5min, gcTime: 10min configured
  □ Zustand for UI state (modals, dropdowns)
  □ URL state for filters/pagination
  □ React Hook Form + Zod for forms

PERFORMANCE:
  □ React.memo for expensive components
  □ useMemo for heavy calculations
  □ Next.js Image component used
  □ Code splitting with dynamic imports
  □ Bundle analyzed and under limits

TESTING:
  □ Unit tests with Vitest + RTL
  □ MSW for API mocking
  □ Playwright for E2E flows
  □ axe-core for a11y testing
  □ 80%+ code coverage target

SECURITY:
  □ No secrets in client code
  □ CSRF token verified
  □ Multi-tenant isolation enforced
  □ Role-based access gated
  □ Proper error boundaries in place

See Also

• references/state-management-patterns.ts: React Query, Zustand, form examples
• references/error-boundary-patterns.tsx: Error.tsx and Suspense implementations
• references/performance-checklist.md: Detailed performance optimization guide
• references/testing-patterns.test.ts: Vitest, RTL, MSW examples