/moai-ref-react-patterns

name: moai-ref-react-patterns
description: >
  React/Next.js component design patterns, state management strategies, and project
  structure reference for frontend development. Agent-extending skill that amplifies
  frontend domain work (spawned via Agent(general-purpose) with frontend instructions)
  with production-grade React patterns.
  NOT for: backend API design, database modeling, DevOps, mobile apps.

when_to_use: >
  Use for React/Next.js component design patterns: state-management
  strategies, hooks, component composition, and project structure.
  Amplifies frontend domain work (Agent(general-purpose) with frontend
  instructions) with production-grade React patterns.

user-invocable: false
metadata:
  version: "1.0.0"
  category: "domain"
  status: "active"
  updated: "2026-03-30"
  tags: "react, nextjs, component, patterns, frontend, reference"

# MoAI Extension: Progressive Disclosure
progressive_disclosure:
  enabled: true
  level1_tokens: 100
  level2_tokens: 3000

React Patterns Reference

Target Spawn

Frontend domain work spawned via `Agent(general-purpose)` with frontend instructions - Applies these patterns directly to component design and state management.

Component Design Patterns

1. Compound Components

Parent and child share implicit state via Context.

Suited for: Tab, Accordion, Dropdown, Select Structure: `<Select>` + `<Select.Trigger>` + `<Select.Option>`

2. Custom Hooks (Extraction Pattern)

Extract state logic into reusable hooks.

Suited for: Form management, API calls, localStorage, debounce Naming: `use` prefix required - `useForm`, `useDebounce`, `useAuth`

3. Container/Presentational Separation

Separate data logic (Container) from UI (Presentational).

Suited for: Large apps, when testability is needed Container: Data fetch, state management, event handlers Presentational: Renders only from props, functionally pure

4. Headless Component

Provides behavior/state without UI.

Suited for: Design system-independent logic Examples: headless `useCombobox`, `useDialog`, `useTable`

State Management Selection Guide

| State Type | Tool | Rationale | |-----------|------|-----------| | UI Local | useState, useReducer | Component-internal | | Server State | React Query / TanStack Query | Caching, refetch, optimistic | | Global Client | Zustand | Concise, minimal boilerplate | | Complex Global | Zustand + Immer | Immutability convenience | | URL State | nuqs / useSearchParams | Filters, pagination | | Form State | React Hook Form + Zod | Integrated validation | | Theme/i18n | Context + Provider | Low change frequency |

Decision Flow

Restorable from URL? -> URL state (nuqs)
Server data? -> React Query
Shared across components? -> Zustand
Component-internal? -> useState
Complex transitions? -> useReducer

Next.js App Router Structure

src/
├── app/                    # App Router
│   ├── (auth)/             # Auth route group
│   │   ├── login/page.tsx
│   │   └── register/page.tsx
│   ├── (main)/             # Main route group
│   │   ├── dashboard/page.tsx
│   │   └── settings/page.tsx
│   ├── api/                # API Routes
│   ├── layout.tsx          # Root layout
│   └── page.tsx            # Home
├── components/
│   ├── ui/                 # Base UI (Button, Input, Modal)
│   └── features/           # Feature components
│       ├── auth/
│       └── dashboard/
├── hooks/                  # Custom hooks
├── lib/                    # Utilities, config
├── stores/                 # Zustand stores
├── types/                  # TypeScript types
└── styles/                 # Global styles

Component Quality Standards

| Item | Standard | |------|----------| | Component Size | Under 200 lines (split if exceeded) | | Props | 5 or fewer (group into object if exceeded) | | Custom Hooks | Always extract when reusing logic | | Error Boundaries | Set at the page level | | Loading States | Provide loading UI for all async ops | | Form Validation | Validate on both client and server |

Performance Patterns

| Pattern | When | Tool | |---------|------|------| | Memoization | Expensive computation | `useMemo`, `React.memo` | | Lazy Loading | Bundle size | `React.lazy`, `next/dynamic` | | Virtualization | 1000+ item lists | `@tanstack/react-virtual` | | Image Optimization | Image loading | `next/image` | | Optimistic Updates | Immediate feedback | React Query `onMutate` | | Debounce | Search, input | `useDeferredValue` or custom hook |

Error Handling

Hierarchical Error Boundaries

RootErrorBoundary (global)
  └── LayoutErrorBoundary (per section)
      └── ComponentErrorFallback (individual)

API Error Handling

| HTTP Status | Client Handling | |------------|----------------| | 401 | Auto logout + redirect | | 403 | Unauthorized UI | | 404 | Not Found page | | 422 | Per-field form error | | 429 | Retry + wait notice | | 500 | Generic error + retry button |

Accessibility Checklist

• [ ] Alt text on all images
• [ ] Keyboard navigation (Tab, Enter, Escape)
• [ ] ARIA labels (aria-label, role)
• [ ] Color contrast 4.5:1 or above
• [ ] Visible focus indicator
• [ ] Semantic HTML (button, nav, main, section)

<!-- moai:evolvable-start id="rationalizations" -->

Common Rationalizations

| Rationalization | Reality | |---|---| | "useEffect is fine for data fetching in React 19" | React 19 provides use() and server components for data fetching. useEffect for fetch is a legacy pattern that causes waterfalls. | | "Global state is simpler than prop drilling" | Global state couples distant components. Prop drilling or composition via children is more predictable and testable. | | "I will add TypeScript types later" | Untyped components accumulate any-typed callers. Retrofitting types into a used component is much harder than starting typed. | | "This component does not need memoization" | Premature memoization is waste, but components rendering lists or expensive trees should be profiled, not assu