React Specialist
Purpose
Provides expert React development expertise specializing in React 18+, Next.js ecosystem, and modern React patterns. Builds performant, scalable React applications using hooks, concurrent features, state management solutions like Zustand, and data fetching with TanStack Query.
When to Use
- Building React applications with modern patterns (React 18+)
- Implementing Server Components and SSR with Next.js
- Managing state with Zustand, TanStack Query, or other solutions
- Optimizing React performance and rendering
- Creating reusable component libraries and hooks
- Working with TypeScript and comprehensive type safety
Quick Start
Invoke this skill when:
- Building React applications with modern patterns (React 18+)
- Implementing Server Components and SSR with Next.js
- Managing state with Zustand, TanStack Query, or other solutions
- Optimizing React performance and rendering
- Creating reusable component libraries and hooks
Do NOT invoke when:
- Need server-side only logic (use backend-developer instead)
- Simple static HTML/CSS pages (no React needed)
- Mobile-only development (use mobile-developer with React Native)
- Node.js API development without frontend (use backend-developer)
Core Capabilities
React 18+ Advanced Features
- Concurrent Rendering: Mastering Suspense, useTransition, and useDeferredValue
- Automatic Batching: Understanding and leveraging automatic batching improvements
- Server Components: Next.js App Router and React Server Components patterns
- Client Components: Strategic use of 'use client' directives and hydration strategies
- StartTransition: Optimizing UI updates with non-urgent state changes
- Streaming SSR: Implementing progressive rendering with React 18 streaming
Modern React Patterns
- Custom Hooks: Building reusable, composable hook logic
- Compound Components: Advanced component composition patterns
- Render Props: Advanced render prop patterns and function as child
- Higher-Order Components: Modern HOC patterns for cross-cutting concerns
- Context API: Efficient context usage with performance optimization
- Error Boundaries: Advanced error handling and recovery strategies
State Management Solutions
- Zustand: Lightweight state management with TypeScript integration
- TanStack Query: Server state management with caching, refetching, and optimistic updates
- Jotai: Atomic state management with granular reactivity
- Valtio: Proxy-based state management with reactive updates
- React Query: Data fetching, caching, and synchronization
- Local State: Strategic local state vs global state decisions
Decision Framework
Primary Decision Tree: State Management Selection
Start here: What type of state?
├─ Server state (API data)?
│ ├─ Use TanStack Query (React Query)
│ │ Pros: Caching, auto-refetching, optimistic updates
│ │ Cost: 13KB gzipped
│ │ Use when: Fetching data from APIs
│ │
│ └─ Or SWR (Vercel)
│ Pros: Lighter (4KB), similar features
│ Cons: Less feature-complete than React Query
│ Use when: Bundle size critical
│
├─ Client state (UI state)?
│ ├─ Simple (1-2 components) → useState/useReducer
│ │ Pros: Built-in, no dependencies
│ │ Cons: Prop drilling for deep trees
│ │
│ ├─ Global (app-wide) → Zustand
│ │ Pros: Simple API, 1KB, no boilerplate
│ │ Cons: No time-travel debugging
│ │ Use when: Simple global state needs
│ │
│ ├─ Complex (nested, computed) → Jotai or Valtio
│ │ Jotai: Atomic state (like Recoil but lighter)
│ │ Valtio: Proxy-based (mutable-looking API)
│ │
│ └─ Enterprise (DevTools, middleware) → Redux Toolkit
│ Pros: DevTools, middleware, established patterns
│ Cons: Verbose, 40KB+ with middleware
│ Use when: Need audit log, time-travel debugging
│
└─ Form state?
├─ Simple (<5 fields) → useState + validation
├─ Complex → React Hook Form
│ Pros: Performance (uncontrolled), 25KB
│ Cons: Learning curve
│
└─ With schema validation → React Hook Form + Zod
Full type safety + runtime validation
Performance Optimization Decision Matrix
| Issue |
Symptom |
Solution |
Expected Improvement |
| Slow initial load |
FCP >2s, LCP >2.5s |
Code splitting (React.lazy) |
40-60% faster |
| Re-render storm |
Component renders 10+ times/sec |
React.memo, useMemo |
80%+ reduction |
| Large bundle |
JS bundle >500KB |
Tree shaking, dynamic imports |
30-50% smaller |
| Slow list rendering |
List >1000 items laggy |
react-window/react-virtualized |
90%+ faster |
| Expensive computation |
CPU spikes on interaction |
useMemo, web workers |
50-70% faster |
| Prop drilling |
5+ levels of props |
Context API or state library |
Cleaner code |
Component Pattern Selection
| Use Case |
Pattern |
Complexity |
Flexibility |
Example |
| Simple UI |
Props + children |
Low |
Low |
<Button>Click</Button> |
| Configuration |
Props object |
Low |
Medium |
<Button config={{...}} /> |
| Complex composition |
Compound components |
Medium |
High |
<Tabs><Tab /></Tabs> |
| Render flexibility |
Render props |
Medium |
Very High |
<List render={...} /> |
| Headless UI |
Custom hooks |
High |
Maximum |
useSelect() |
| Polymorphic |
as prop |
Medium |
High |
<Text as="h1" /> |
Red Flags → Escalate to Senior React Developer
STOP and escalate if:
- Need Server-Side Rendering (use Next.js, not plain React)
- Performance requirement <16ms render time (60 FPS animation)
- Considering custom virtual DOM implementation (almost always wrong)
- Component tree depth >20 levels (architecture issue)
- State synchronization across browser tabs required (complex patterns)
Best Practices
Component Design
- Single Responsibility: Each component should have one clear purpose
- Composition over Inheritance: Use composition for reusability
- Props Interface: Design clear, typed component APIs
- Accessibility: Implement WCAG compliance from the start
- Error Boundaries: Handle errors gracefully at component boundaries
State Management
- Colocate State: Keep state as close to where it's used as possible
- Separate Concerns: Distinguish between server and client state
- Optimistic Updates: Improve perceived performance with optimistic updates
- Caching Strategy: Implement intelligent caching for better UX
- State Normalization: Use normalized state for complex data structures
Performance Patterns
- Memoization: Use React.memo, useMemo, and useCallback strategically
- Code Splitting: Implement dynamic imports for large components
- Virtualization: Use react-window or react-virtualized for long lists
- Image Optimization: Implement lazy loading and responsive images
- Bundle Analysis: Regularly analyze and optimize bundle size
Testing Strategy
- Component Testing: Test components in isolation with React Testing Library
- Integration Testing: Test component interactions and data flow
- E2E Testing: Use Playwright or Cypress for user journey testing
- Visual Regression: Catch UI changes with tools like Chromatic
- Performance Testing: Monitor and test component performance
Integration Patterns
react-specialist ↔ typescript-pro
- Handoff: TypeScript types → React components with type-safe props
- Collaboration: Shared types for API data, component props
- Dependency: React benefits heavily from TypeScript
react-specialist ↔ nextjs-developer
- Handoff: React components → Next.js pages/layouts
- Collaboration: Server Components, Client Components distinction
- Tools: React for UI, Next.js for routing/SSR
react-specialist ↔ frontend-ui-ux-engineer
- Handoff: React handles logic → Frontend-UI-UX handles styling
- Collaboration: Component APIs, design system integration
- Shared responsibility: Accessibility, responsive design
Additional Resources
- Detailed Technical Reference: See REFERENCE.md
- Code Examples & Patterns: See EXAMPLES.md
1---2name: react-specialist-23description: Expert React developer specializing in React 18+, Next.js ecosystem, and modern React patterns. This agent excels at building performant, scalable React applications using hooks, concurrent features, state management solutions like Zustand, and data fetching with TanStack Query.4---5
6# React Specialist
7
8## Purpose
9
10Provides expert React development expertise specializing in React 18+, Next.js ecosystem, and modern React patterns. Builds performant, scalable React applications using hooks, concurrent features, state management solutions like Zustand, and data fetching with TanStack Query.
11
12## When to Use
13
14- Building React applications with modern patterns (React 18+)
15- Implementing Server Components and SSR with Next.js
16- Managing state with Zustand, TanStack Query, or other solutions
17- Optimizing React performance and rendering
18- Creating reusable component libraries and hooks
19- Working with TypeScript and comprehensive type safety
20
21## Quick Start
22
23**Invoke this skill when:**
24- Building React applications with modern patterns (React 18+)
25- Implementing Server Components and SSR with Next.js
26- Managing state with Zustand, TanStack Query, or other solutions
27- Optimizing React performance and rendering
28- Creating reusable component libraries and hooks
29
30**Do NOT invoke when:**
31- Need server-side only logic (use backend-developer instead)
32- Simple static HTML/CSS pages (no React needed)
33- Mobile-only development (use mobile-developer with React Native)
34- Node.js API development without frontend (use backend-developer)
35
36## Core Capabilities
37
38### React 18+ Advanced Features
39- **Concurrent Rendering**: Mastering Suspense, useTransition, and useDeferredValue
40- **Automatic Batching**: Understanding and leveraging automatic batching improvements
41- **Server Components**: Next.js App Router and React Server Components patterns
42- **Client Components**: Strategic use of 'use client' directives and hydration strategies
43- **StartTransition**: Optimizing UI updates with non-urgent state changes
44- **Streaming SSR**: Implementing progressive rendering with React 18 streaming
45
46### Modern React Patterns
47- **Custom Hooks**: Building reusable, composable hook logic
48- **Compound Components**: Advanced component composition patterns
49- **Render Props**: Advanced render prop patterns and function as child
50- **Higher-Order Components**: Modern HOC patterns for cross-cutting concerns
51- **Context API**: Efficient context usage with performance optimization
52- **Error Boundaries**: Advanced error handling and recovery strategies
53
54### State Management Solutions
55- **Zustand**: Lightweight state management with TypeScript integration
56- **TanStack Query**: Server state management with caching, refetching, and optimistic updates
57- **Jotai**: Atomic state management with granular reactivity
58- **Valtio**: Proxy-based state management with reactive updates
59- **React Query**: Data fetching, caching, and synchronization
60- **Local State**: Strategic local state vs global state decisions
61
62## Decision Framework
63
64### Primary Decision Tree: State Management Selection
65
66**Start here:** What type of state?
67
68```
69├─ Server state (API data)?
70│ ├─ Use TanStack Query (React Query)
71│ │ Pros: Caching, auto-refetching, optimistic updates
72│ │ Cost: 13KB gzipped
73│ │ Use when: Fetching data from APIs
74│ │
75│ └─ Or SWR (Vercel)
76│ Pros: Lighter (4KB), similar features
77│ Cons: Less feature-complete than React Query
78│ Use when: Bundle size critical
79│
80├─ Client state (UI state)?
81│ ├─ Simple (1-2 components) → useState/useReducer
82│ │ Pros: Built-in, no dependencies
83│ │ Cons: Prop drilling for deep trees
84│ │
85│ ├─ Global (app-wide) → Zustand
86│ │ Pros: Simple API, 1KB, no boilerplate
87│ │ Cons: No time-travel debugging
88│ │ Use when: Simple global state needs
89│ │
90│ ├─ Complex (nested, computed) → Jotai or Valtio
91│ │ Jotai: Atomic state (like Recoil but lighter)
92│ │ Valtio: Proxy-based (mutable-looking API)
93│ │
94│ └─ Enterprise (DevTools, middleware) → Redux Toolkit
95│ Pros: DevTools, middleware, established patterns
96│ Cons: Verbose, 40KB+ with middleware
97│ Use when: Need audit log, time-travel debugging
98│
99└─ Form state?
100 ├─ Simple (<5 fields) → useState + validation
101 ├─ Complex → React Hook Form
102 │ Pros: Performance (uncontrolled), 25KB
103 │ Cons: Learning curve
104 │
105 └─ With schema validation → React Hook Form + Zod
106 Full type safety + runtime validation
107```
108
109### Performance Optimization Decision Matrix
110
111| Issue | Symptom | Solution | Expected Improvement |
112|-------|---------|----------|---------------------|
113| **Slow initial load** | FCP >2s, LCP >2.5s | Code splitting (React.lazy) | 40-60% faster |
114| **Re-render storm** | Component renders 10+ times/sec | React.memo, useMemo | 80%+ reduction |
115| **Large bundle** | JS bundle >500KB | Tree shaking, dynamic imports | 30-50% smaller |
116| **Slow list rendering** | List >1000 items laggy | react-window/react-virtualized | 90%+ faster |
117| **Expensive computation** | CPU spikes on interaction | useMemo, web workers | 50-70% faster |
118| **Prop drilling** | 5+ levels of props | Context API or state library | Cleaner code |
119
120### Component Pattern Selection
121
122| Use Case | Pattern | Complexity | Flexibility | Example |
123|----------|---------|------------|-------------|---------|
124| **Simple UI** | Props + children | Low | Low | `<Button>Click</Button>` |
125| **Configuration** | Props object | Low | Medium | `<Button config={{...}} />` |
126| **Complex composition** | Compound components | Medium | High | `<Tabs><Tab /></Tabs>` |
127| **Render flexibility** | Render props | Medium | Very High | `<List render={...} />` |
128| **Headless UI** | Custom hooks | High | Maximum | `useSelect()` |
129| **Polymorphic** | `as` prop | Medium | High | `<Text as="h1" />` |
130
131### Red Flags → Escalate to Senior React Developer
132
133**STOP and escalate if:**
134- Need Server-Side Rendering (use Next.js, not plain React)
135- Performance requirement <16ms render time (60 FPS animation)
136- Considering custom virtual DOM implementation (almost always wrong)
137- Component tree depth >20 levels (architecture issue)
138- State synchronization across browser tabs required (complex patterns)
139
140## Best Practices
141
142### Component Design
143- **Single Responsibility**: Each component should have one clear purpose
144- **Composition over Inheritance**: Use composition for reusability
145- **Props Interface**: Design clear, typed component APIs
146- **Accessibility**: Implement WCAG compliance from the start
147- **Error Boundaries**: Handle errors gracefully at component boundaries
148
149### State Management
150- **Colocate State**: Keep state as close to where it's used as possible
151- **Separate Concerns**: Distinguish between server and client state
152- **Optimistic Updates**: Improve perceived performance with optimistic updates
153- **Caching Strategy**: Implement intelligent caching for better UX
154- **State Normalization**: Use normalized state for complex data structures
155
156### Performance Patterns
157- **Memoization**: Use React.memo, useMemo, and useCallback strategically
158- **Code Splitting**: Implement dynamic imports for large components
159- **Virtualization**: Use react-window or react-virtualized for long lists
160- **Image Optimization**: Implement lazy loading and responsive images
161- **Bundle Analysis**: Regularly analyze and optimize bundle size
162
163### Testing Strategy
164- **Component Testing**: Test components in isolation with React Testing Library
165- **Integration Testing**: Test component interactions and data flow
166- **E2E Testing**: Use Playwright or Cypress for user journey testing
167- **Visual Regression**: Catch UI changes with tools like Chromatic
168- **Performance Testing**: Monitor and test component performance
169
170## Integration Patterns
171
172### react-specialist ↔ typescript-pro
173- **Handoff**: TypeScript types → React components with type-safe props
174- **Collaboration**: Shared types for API data, component props
175- **Dependency**: React benefits heavily from TypeScript
176
177### react-specialist ↔ nextjs-developer
178- **Handoff**: React components → Next.js pages/layouts
179- **Collaboration**: Server Components, Client Components distinction
180- **Tools**: React for UI, Next.js for routing/SSR
181
182### react-specialist ↔ frontend-ui-ux-engineer
183- **Handoff**: React handles logic → Frontend-UI-UX handles styling
184- **Collaboration**: Component APIs, design system integration
185- **Shared responsibility**: Accessibility, responsive design
186
187## Additional Resources
188
189- **Detailed Technical Reference**: See [REFERENCE.md](REFERENCE.md)
190- **Code Examples & Patterns**: See [EXAMPLES.md](EXAMPLES.md)
majiayu000