Guide Expert React Frontend

Develops modern React 19.2 applications with hooks-first architecture, Server Components, and concurrent rendering patterns.

When to Use This Agent

Choose this agent when you need to:

• Build React 19.2 apps using use(), useFormStatus, useOptimistic, and useEffectEvent hooks
• Implement Server Component boundaries, Activity component, and concurrent transitions
• Architect component libraries with TypeScript generics and comprehensive testing

Consider alternatives when:

• Your project is locked to React 17 or earlier without hooks support
• You need framework-level routing and SSR from Next.js or Remix-specific agents

Quick Start

Configuration

Copy
name: guide-expert-react-frontend
type: agent
category: web-tools

Example Invocation

Copy
claude agent:invoke guide-expert-react-frontend "Build a form with useActionState and optimistic updates"

Example Output

Created: components/CreatePostForm.tsx
  - useActionState for submission lifecycle
  - useOptimistic for instant UI feedback
  - useFormStatus in SubmitButton for pending state
  - Progressive enhancement (works without JS)
Created: actions/createPost.ts
  - Server Action with typed FormState return
Created: components/CreatePostForm.test.tsx

Core Concepts

React 19.2 Feature Landscape

Aspect	Details
use() Hook	Suspense-compatible promise and context consumption for data fetching
Activity Component	UI visibility manager preserving state across show/hide transitions
useEffectEvent	Extracts non-reactive logic from effects without dependency bloat
Ref as Prop	Direct ref passing without forwardRef, simplifying component APIs
Context Without Provider	Render context directly instead of Context.Provider wrappers

Component Architecture

+-------------------+     +-------------------+     +------------------+
|  Server           |---->|  Client           |---->|  Interactive     |
|  Components       |     |  Boundary         |     |  Components      |
|  (data fetching)  |     |  ('use client')   |     |  (hooks/events)  |
+-------------------+     +-------------------+     +------------------+
       |                         |                         |
       v                         v                         v
+-------------------+     +-------------------+     +------------------+
|  Suspense         |     |  Activity         |     |  Error           |
|  Boundaries       |     |  (state preserve) |     |  Boundaries      |
+-------------------+     +-------------------+     +------------------+

Configuration

Parameter	Type	Default	Description
react_version	string	"19.2"	React version for feature-specific hook guidance
typescript_mode	string	"strict"	TypeScript strictness level
testing_framework	string	"vitest"	Test runner: "vitest", "jest", or "playwright"
state_management	string	"context"	Default: "context", "zustand", or "redux-toolkit"
styling_approach	string	"tailwind"	Styling: "tailwind", "css-modules", or "styled-components"

Best Practices

1. Start with Server Components - Every component should begin as a Server Component that fetches its own data. Only add 'use client' when genuinely needing useState, event handlers, or browser APIs.

2. Use useEffectEvent for Decoupling - When an effect needs a frequently changing value (theme, locale) but should not re-execute, extract that access into useEffectEvent. This keeps dependency arrays honest.

3. Prefer use() Over useEffect for Data - The use() hook integrates with Suspense to handle loading states declaratively, eliminating manual loading/error/data state triples.

4. Leverage Activity for Tab Preservation - Wrap tabbed panels in <Activity> with mode="visible"/"hidden" to preserve form inputs, scroll positions, and timers across switches.

5. Pass Refs as Props Directly - React 19 eliminated forwardRef. Define ref as a regular prop in TypeScript interfaces for cleaner, more readable component APIs.

Common Issues

1. Stale Closures in useEffectEvent - useEffectEvent must only be called from effects or event handlers. Calling during render leads to timing issues where captured values lag behind state.

2. Suspense Boundary Too High - A single Suspense around an entire page shows one fallback for all async operations. Place boundaries around individual async components for progressive reveal.

3. Optimistic State After Failure - When useOptimistic succeeds in UI but the server action fails, state snaps back silently. Always pair optimistic updates with error handling that surfaces a notification.