arbazkhan971/react

Activate When

• /godmode:react, "React app", "component architecture"
• "state management", "React performance", "re-renders"
• "hooks", "Server Components", "React Testing Library"
• "React component", "build a react", "react component"

Workflow

1. Project Assessment

grep -E "react|zustand|jotai|redux|react-query" \
  package.json 2>/dev/null
grep -r "use client\|use server" \
  --include="*.tsx" -l 2>/dev/null | head -10

Framework: Next.js | Remix | Vite | CRA
React: 18 | 19+ | Rendering: SPA | SSR | SSG
Pain points: re-renders, prop drilling, bundle size

2. Component Architecture

Composition (default): small focused components, slot pattern for layouts. Custom Hooks: extract stateful logic (useDebounce, useMediaQuery, useLocalStorage). Render Props: when parent controls rendering.

Hierarchy: Pages -> Features -> UI Components -> Atoms. Rules: one thing per component, small props, composition over configuration, feature folders over tech folders.

3. State Management

| Type | Solution | |--|--| | Server/async (API) | TanStack Query / SWR | | URL (params) | useSearchParams / nuqs | | Form | React Hook Form + Zod | | Local UI | useState / useReducer | | Shared UI | Zustand or Jotai | | Complex global | Zustand or Redux Toolkit |

IF bundle >500KB: enable code splitting. IF re-renders >3 per interaction: add memoization.

4. Performance

1. React.memo: only with measured evidence
2. useMemo: only for expensive computations (>1ms)
3. useCallback: only when passed to memo'd child
4. Code splitting: lazy() + Suspense at route level
5. Virtualization: @tanstack/react-virtual for 100+ items
6. Suspense: for data fetching

GOLDEN RULE: measure before optimizing. Use React DevTools Profiler.

5. Server Components & Concurrent

RSC: server-only, zero client JS, direct DB access. useTransition: non-urgent state updates. useDeferredValue: defer expensive re-renders.

6. Testing

Pyramid: E2E (Playwright) -> Integration (RTL) -> Unit. Query priority: getByRole > getByLabelText > getByText

getByTestId (last resort). Rules: test behavior not implementation. userEvent > fireEvent. MSW for API mocking.

7. Audit

[ ] Composition over prop drilling
[ ] Custom hooks for reusable logic
[ ] State management per category
[ ] memo/useMemo with evidence only
[ ] Code splitting at route level
[ ] Error boundaries
[ ] Tests with accessible queries
[ ] TypeScript strict

<!-- tier-3 -->

Quality Targets

• Target: <16ms render cycle (60fps)
• Target: <100KB component bundle size per route
• Re-render count: 0 unnecessary re-renders detected by profiler

Hard Rules

1. NEVER use any. Use unknown + type guard.
2. NEVER business logic in components.
3. NEVER useEffect for derived state.
4. NEVER memo without Profiler evidence.
5. NEVER test implementation details.
6. NEVER index as key for reorderable lists.
7. NEVER prop-drill past 2 levels.
8. ALWAYS tsc --noEmit after changes.
9. ALWAYS query by role first in tests.
10. ALWAYS colocate component + hook + test.

TSV Logging

Append .godmode/react-results.tsv:

timestamp	action	components	hooks	test_status	build_status	notes

Keep/Discard

KEEP if: tsc passes AND tests pass AND no new
  ESLint warnings AND bundle size stable.
DISCARD if: type errors OR test failures OR hooks
  rules violated OR bundle regressed.

Stop Conditions

STOP when ALL of:
  - tsc --noEmit exits 0
  - All tests pass
  - No ESLint react-hooks warnings
  - Bundle within budget

Autonomous Operation

On failure: git reset --hard HEAD~1. Never pause.

Error Recovery

| Failure | Action | |--|--| | Infinite re-render | Check useEffect deps, stabilize refs | | Hydration mismatch | useEffect for client-only code | | Bundle too large | Analyze, lazy-load routes | | State on unmounted | Cleanup in useEffect, AbortController |