React — Overview

OWNER: floris, floor ALSO_USED_BY: alexander, tobias LAST_VERIFIED: 2026-03-26 GE_STACK_VERSION: React 19.x (19.1+)

---

Overview

React is GE's UI library for all client-facing applications. Used exclusively with TypeScript strict mode inside Next.js App Router. All components default to Server Components unless client interactivity is required.

---

Version Policy

GE_STACK_VERSION: 19.1+ CHECK: React version in package.json is 19.x IF: version is below 19.0 THEN: upgrade immediately — GE patterns depend on React 19 APIs

React 19 features GE relies on: - useActionState for form mutation state - useOptimistic for instant UI feedback - use() API for conditional resource reading - useFormStatus for nested form components - Server Components (stable) - <form action={}> with Server Actions - React Compiler (auto-memoization — replaces manual useMemo/useCallback in most cases)

---

GE Conventions

File Organization

CHECK: component files use PascalCase CHECK: hook files use camelCase with use prefix CHECK: one exported component per file

components/
  ui/               # shadcn/ui primitives (DO NOT EDIT)
  [feature]/
    feature-name.tsx          # main component
    feature-name.types.ts     # types/interfaces
    feature-name.hooks.ts     # feature-specific hooks
    feature-name.utils.ts     # pure helper functions

Component Conventions

CHECK: every component has explicit return type annotation CHECK: props interface is exported and named {Component}Props CHECK: destructure props in function signature CHECK: no default exports — use named exports only

export interface UserCardProps {
  user: User;
  variant?: "compact" | "full";
}

export function UserCard({ user, variant = "compact" }: UserCardProps): React.ReactElement {
  return <div>...</div>;
}

Server Components First

CHECK: component has NO "use client" directive by default IF: component uses useState, useEffect, event handlers, or browser APIs THEN: add "use client" at top of file IF: only a small part of the tree needs interactivity THEN: extract that part into a separate client component

ANTI_PATTERN: adding "use client" to a layout or page component FIX: push client boundaries down to the smallest interactive leaf

TypeScript Strict Mode

CHECK: tsconfig has "strict": true CHECK: no any types — use unknown and narrow CHECK: no non-null assertions (!) — use type guards CHECK: all event handlers are explicitly typed

---

React 19 API Usage

useActionState (replaces useFormState)

CHECK: form mutations use useActionState not manual useState+fetch IF: building a form that calls a Server Action THEN: use useActionState for pending/error/result state

useOptimistic

CHECK: mutations with visible delay use useOptimistic IF: user action produces server round-trip > 200ms THEN: show optimistic result immediately, revert on error

use() API

CHECK: conditional data reading uses use() not useEffect+useState IF: component needs to read a promise or context conditionally THEN: use use() — it can be called inside conditionals and loops

React Compiler

CHECK: do NOT add manual useMemo/useCallback for render optimization IF: React Compiler is enabled in next.config THEN: compiler handles memoization automatically IF: profiling shows a specific bottleneck the compiler misses THEN: add manual memo with a comment explaining why

---

Styling

CHECK: all styling uses Tailwind CSS utility classes CHECK: component variants use cva (class-variance-authority) CHECK: conditional classes use cn() utility from @/lib/utils IF: a shadcn/ui component exists for the pattern THEN: use it — do NOT build custom

ANTI_PATTERN: inline style objects FIX: use Tailwind classes or cva variants

ANTI_PATTERN: CSS modules or styled-components FIX: Tailwind + cn() covers all GE use cases

---

Testing

CHECK: components have co-located test files (feature-name.test.tsx) CHECK: tests use Vitest + React Testing Library CHECK: test user behavior, not implementation details IF: component has complex conditional rendering THEN: test each branch with descriptive test names

---

Cross-References

READ_ALSO: wiki/docs/stack/react/patterns.md READ_ALSO: wiki/docs/stack/react/state-management.md READ_ALSO: wiki/docs/stack/react/forms.md READ_ALSO: wiki/docs/stack/react/pitfalls.md READ_ALSO: wiki/docs/stack/react/checklist.md READ_ALSO: wiki/docs/stack/nextjs/index.md