React Architecture

Targets React 19 with TypeScript strict. Component library defaults to Radix primitives + Tailwind (covered deeply in ui-ux-architect). When this skill applies to Next.js apps, server-side concerns live in nextjs-architect. See STACK.md for pinned dependencies.

1. TypeScript posture — strict, always

tsconfig.json baseline in RECIPES.md § tsconfig.json — strict baseline.

• No any. Use unknown for truly untyped boundaries, then narrow.
• No type assertions (as) except at validated I/O boundaries (after a Zod parse, etc.).
• noUncheckedIndexedAccess is on — arr[0] is T | undefined, you handle the undefined. Catches a whole class of runtime crashes.
• exactOptionalPropertyTypes distinguishes {x?: string} from {x: string | undefined}. Pick the right one per use case.
• Discriminated unions over enum + cast. type Status = {kind: "loading"} | {kind: "ok"; data: T} | {kind: "err"; msg: string}.

2. Project structure — feature-based

Mirrors fastapi-architect and gin-architect — same shape, different language. One folder per bounded feature. Full tree in RECIPES § Feature-based project structure.

• A feature folder owns its UI, hooks, types, schemas, and API queries. Cross-feature reuse moves to src/components/.
• schemas.ts per feature — Zod schemas for every request body and response shape. Parse at the API boundary; throw on parse failure.
• index.ts exports the public surface of each feature. Importing from features/users/components/UserList is cheating; import from features/users and re-export deliberately.

3. Components

Function components only

• No class components. Hooks cover every legitimate case.
• One component per file. File name matches the component name (UserList.tsx exports UserList).
• Default export sparingly. Named exports compose better with refactors and IDE tooling.

Naming + structure

Skeleton: RECIPES.md § Component skeleton — Props type + loading/error guard.

• Props type colocated, named <Component>Props.
• Loading / error / empty states are real components, not inline ternaries with cryptic JSX. Per ui-ux-architect.
• aria-* attributes when the role isn't implicit. Per ui-ux-architect.
• Event handlers passed as props, not constructed inside the component (which would change identity every render and break memo).

Composition over configuration

Reach for the composition shape first; a 20-prop <DataTable> is a smell. Comparison: RECIPES.md § Compound vs. configuration component shape.

• Compound components export sub-components on the main one (Tabs.List, Tabs.Tab, Tabs.Panel).
• children is the most underused prop. When in doubt, accept children.
• Render props / function-as-child for advanced cases where parent needs the child's state. Use sparingly — usually a custom hook is cleaner.

Memoization, sparingly

• Don't memo everything. React 19's compiler handles most cases. Profile before memoizing.
• useMemo / useCallback justified only when:
  • The memoized value is itself expensive to compute, or
  • It's passed to a memoized child and identity matters.
• The wrong reason to add memo: "to feel safe". Often actively counterproductive (memoize an object that always changes → worse than not memoizing).

4. Hooks

Built-in hooks

Full table of when to use each (useState, useReducer, useContext, useEffect, useLayoutEffect, useId, useTransition, useDeferredValue, use) in RECIPES § Built-in hooks reference. Key rule: useEffect is for synchronization with non-React systems, not for fetching — TanStack Query handles fetching.

Custom hooks

• Encapsulate stateful behavior that's reused or that doesn't fit in a component. useUser(id), useDebounce(value, ms), useEscapeKey(handler).
• Name starts with use — React's lint depends on it.
• One responsibility per hook. useUserAndPostsAndPreferences is three hooks.
• Custom hooks compose other hooks freely. No reason to inline what could be useUser(id).

Don't fetch in useEffect

• Server state lives in TanStack Query, not useState + useEffect. The fetch-in-effect pattern is correct for ~zero apps.
• The query handles loading, error, retry, dedup, caching, refetch on focus, invalidation — none of which you want to reimplement.

5. State management — three layers

TanStack Query for server state

• Query keys are arrays, hierarchically structured. ["users", { filter, sort, cursor }]. Drives invalidation patterns.
• Define query keys + fetchers per feature in features/<feature>/api.ts.
• Stale time tuned per resource — staleTime: 1000 * 60 is a reasonable default; reference data can go higher.
• refetchOnWindowFocus: true as default. Modern app expectation.
• Optimistic updates for mutations that the user will see succeed in 99% of cases (likes, votes, simple edits). Roll back on error. The query lib supports this directly with onMutate + onError rollback.
• Don't put server data in zustand. Caching, dedup, and freshness already live in TanStack Query; duplicating them is a recipe for inconsistency.

Context for cross-tree static-ish state

• Auth context, theme context, locale context — read by many components, changes rarely.
• Stable provider value — wrap in useMemo so consumers don't re-render on every parent render. Or split into one provider for the value and one for the dispatcher.

zustand for the rest

• When Context performance is a problem (many consumers re-render on every change), zustand selectors fix it.
• When state has a non-trivial reducer shape with several actions, zustand's set/get is cleaner than useReducer + Context.
• Don't reach for it preemptively. Most apps go years without needing it.

Skeleton: RECIPES.md § Zustand store — focused, single-purpose.

6. Suspense + ErrorBoundary

React 19's recommendation is: every async boundary has a Suspense + ErrorBoundary above it. Skeleton: RECIPES.md § Suspense + ErrorBoundary at a route.

• <Suspense> for loading, <ErrorBoundary> for errors. The two together replace per-component if (isPending) ... if (isError) ... ladders.
• TanStack Query supports Suspense mode (useSuspenseQuery) — pairs cleanly with the boundary pattern.
• Granularity matters. A single big Suspense for the whole page means one slow query blocks everything. A Suspense per logical region means each fills in as ready.

7. Forms

• Controlled inputs for everything user-typed. useState per field for simple forms; react-hook-form (default for non-trivial) for complex forms with cross-field validation.
• Zod schemas validate on submit (and optionally on blur for inline feedback). Same schema feeds the API request type.
• Native HTML form semantics — <form>, `<label