ia-react-frontend

React Frontend

Verify before implementing: For App Router patterns, React 19 APIs, or version-specific behavior, look up current docs (Context7 query-docs if available, else the framework's official docs via web search) before writing code. Training data may lag current releases.

Component TypeScript

• Extend native elements with ComponentPropsWithoutRef<'button'>, add custom props via intersection
• Use React.ReactNode for children, React.ReactElement for single element, render prop (data: T) => ReactNode
• Discriminated unions for variant props -- TypeScript narrows automatically in branches
• Generic components: `` with keyof T for column keys, T extends { id: string } for constraints
• Event types: React.MouseEvent, FormEvent, ChangeEvent
• as const for custom hook tuple returns
• useRef(null) for DOM (use ?.), useRef(0) for mutable values
• Explicit useState(null) for unions/null
• useReducer actions as discriminated unions: { type: 'set'; payload: number } | { type: 'reset' }
• useContext null guard: throw in custom useX() hook if context is null

Effects Decision Tree

Effects are escape hatches -- most logic should NOT use effects.

Effect rules:

• Never suppress the linter -- fix the code instead
• Use updater functions (setItems(prev => [...prev, item])) to remove state dependencies
• Move objects/functions inside effects to stabilize dependencies
• useEffectEvent for non-reactive values (e.g., theme in a connection effect)
• Always return cleanup for subscriptions, connections, listeners
• Data fetching cancellation (pick by situation): AbortController for fetch; ignore flag for non-cancellable promises; React Query handles both automatically

Concurrency & Race Classes

Five race classes survive type-checking and unit tests -- hunt each one during review (cleanup/cancellation mechanics: Effect rules above):

State Management

Local UI state       → useState, useReducer
Shared client state  → Zustand (simple) | Redux Toolkit (complex)
Atomic/granular      → Jotai
Server/remote data   → React Query (TanStack Query)
URL state            → nuqs, router search params
Form state           → React Hook Form

Key patterns:

• Zustand: create()(devtools(persist((set) => ({...})))) -- use slices for scale, selective subscriptions to prevent re-renders
• React Query: query keys factory (['users', 'detail', id] as const), staleTime/gcTime, optimistic updates with onMutate/onError rollback
• Never duplicate server data (React Query) in a client store (Zustand)
• Colocate state close to where it's used

Performance

Critical -- eliminate waterfalls:

• Promise.all() for independent async operations
• Move await into branches where actually needed
• Suspense boundaries to stream slow content

Critical -- bundle size:

• Import directly from modules, avoid barrel files (index.ts re-exports)
• next/dynamic or React.lazy() for heavy components
• Defer third-party scripts (analytics, logging) until after hydration
• Preload on hover/focus for perceived speed
• content-visibility: auto + contain-intrinsic-size on long lists -- skips off-screen layout/paint

Re-render optimization:

• Never define a component inside another component. Each parent render creates a new function identity, and React compares element types to decide whether to update or replace -- a new type means the whole subtree unmounts and remounts, so local state is lost, effects re-run, and DOM nodes are recreated. Symptoms are behavioral, not slow: an input loses focus on every keystroke, animations restart, scroll position resets. Hoist the component to module scope and pass what it needed via props. The React Compiler does not save this one -- the type identity changes before memoization applies
• Derive state during render, not in effects
• Subscribe to derived booleans, not raw objects (state.items.length > 0 not state.items)
• Functional setState for stable callbacks: setCount(c => c + 1)
• Lazy state init: useState(() => expensiveComputation())
• useTransition for non-urgent updates (search filtering)
• useDeferredValue for expensive derived UI
• Don't subscribe to searchParams/state read only in callbacks -- read on demand
• Use ternary (condition ? : ), not && for conditionals
• React.memo only for expensive subtrees with stable props
• Hoist static JSX outside components

React Compiler (React 19): auto-memoizes -- write idiomatic React, remove manual useMemo/useCallback/memo. Enable via reactCompiler: true in next.config (non-framework: babel-plugin-react-compiler). Keep components pure.

React 19

• ref as prop -- forwardRef deprecated. Accept ref?: React.Ref as regular prop
• useActionState -- replaces useFormState: const [state, formAction, isPending] = useActionState(action, initialState)
• use() -- unwrap Promise or Context during render (not in callbacks/effects). Enables conditional context reads
• useOptimistic -- const [optimistic, addOptimistic] = useOptimistic(state, mergeFn) for instant UI feedback
• useFormStatus -- const { pending } = useFormStatus() in child of ``
• Server Components -- default in App Router. Async, access DB/secrets directly. No hooks, no event handlers
• Server Actions -- 'use server' directive. Validate inputs (Zod), revalidateTag/revalidatePath after mutations. Server Actions are public endpoints -- always verify auth/authz inside each action, not just in middleware or layout guards
• `` -- preserves state/DOM for toggled components (experimental)

Next.js App Router

File conventions: page.tsx (route UI), layout.tsx (shared wrapper), template.tsx (re-mounted on navigation, unlike layout), loading.tsx (Suspense), error.tsx (error boundary), not-found.tsx (404), default.tsx (parallel route fallback), route.ts (API endpoint)

Rendering modes: Server Components (default) | Client ('use client') | Static (build) | Dynamic (request) | Streaming (progressive)

Decision: Server Component unless it needs hooks, event handlers, or browser APIs. Split: server parent + client child. Isolate interactive components as 'use client' leaf components -- keep server components static with no global state or event handlers.

Server → client boundary: pass only the fields a client component actually uses, not whole ORM rows or fetch objects. Every prop crossing the 'use client' boundary is serialized into the payload, so a 50-field user object read for one field still ships all 50.

Client-only state that drives first paint (theme, locale, feature flag, auth hint): reading localStorage during render breaks SSR, and reading it in useEffect paints the default first, so the correct value arrives one frame later as a visible flash. Set the value on the document with a small synchronous inline script that runs before hydration -- typically writing a class or data- attribute on `` that CSS already keys on. The script is developer-authored and must never interpolate user, request, or database data; it is the one place dangerouslySetInnerHTML is warranted, and only for a literal string.

Routing patterns:

• Route groups (name) -- organize without affecting URL
• Parallel routes @slot -- independent loading states in same layout
• Intercepting routes (.) -- modal overlays with full-page fallback

Caching:

• fetch(url, { cache: 'force-cache' }) -- static
• fetch(url, { next: { revalidate: 60 } }) -- ISR
• fetch(url, { cache: 'no-store' }) -- dynamic
• Tag-based: fetch(url, { next: { tags: ['products'] } }) then revalidateTag('products')

Data fetching:

• Fetch in Server Components where data is used
• Use Suspense boundaries for slow queries
• React.cache() for per-request dedup
• generateStaticParams for static generation
• generateMetadata for dynamic SEO
• Static metadata with title: { default: 'App', template: '%s | App' } for cascading page titles
• after() for non-blocking side effects (logging, analytics) -- runs after response is sent
• Hoist static I/O (fonts, config) to module level -- runs once, not per request
• Never hold request-scoped or user data in module-level mutable state -- server renders run concurrently in one process, so shared module state leaks across requests (one user's data surfacing in another's response). Hoist only immutable static I/O; keep request data local to the render tree (pass as props)

Testing (Vitest + React Testing Library)

• Component tests: Vitest + RTL, co-located *.test.tsx. Default for React components.
• Hook tests: renderHook + act, co-located *.test.ts
• Unit tests: Vitest for pure functions, utilities, services
• E2E: Playwright for user flows and critical paths
• Query priority: getByRole > getByLabelText > getByPlaceholderText > getByText > getByTestId
• Mock API services and external providers; render child components real for integration confidence
• One behavior per test with AAA structure. Name: should when
• Use userEvent over fireEvent for realistic interactions
• findBy* for async elements, waitFor after state-triggering actions
• vi.clearAllMocks() in beforeEach. Recreate state per test. General testing discipline (anti-patterns, rationalization resistance): see ia-writing-tests skill. See testing patterns and examples for component, hook, and mocking examples. See e2e testing for Playwright patterns.

Tailwind Integration

For Tailwind v4 configuration, utility patterns, dark mode, and component variants, see ia-tailwind-css skill.

Class sorting in JSX: keep Tailwind classes in canonical order (enforce via eslint-plugin-better-tailwindcss).

Discipline

• Simplicity first -- every change as simple as possible, impact minimal code
• Only touch what's necessary -- avoid introducing unrelated changes
• No hacky workarounds -- if a fix feels wrong, step back and implement the clean solution
• Before adding a new abstraction, verify it appears in 3+ places

References

• testing.md -- Component, hook, and mocking test examples
• e2e-testing.md -- Playwright E2E patterns

Verify

• TypeScript compiles with zero errors
• No suppressed lint rules (eslint-disable, @ts-ignore) in new code
• useEffect dependency arrays not manually overridden
• No forwardRef usage in React 19+ projects (use ref prop directly)