) {\n if (items.length === 0) return renderEmpty?.() ?? \n return {items.map((item, i) => - {renderItem(item)}
)}
\n}\n```\n\n**3. Higher-Order Components (for cross-cutting concerns — use sparingly)**\n```tsx\nexport function withAuth(Component: ComponentType
) {\n return function AuthenticatedComponent(props: P) {\n const { user, isLoading } = useAuth()\n if (isLoading) return \n if (!user) return \n return \n }\n}\n```\n\n### 10 Component Rules\n1. **One component per file** — always\n2. **Named exports** — never default exports (refactoring safety)\n3. **Props interface** — always explicit, always exported\n4. **No business logic in components** — extract to hooks\n5. **No inline styles** — use Tailwind classes or CSS modules\n6. **No string refs** — useRef only\n7. **No index as key** — use stable identifiers\n8. **Memo strategically** — not everywhere, only for expensive renders\n9. **Children over props** — prefer composition over configuration\n10. **Accessible by default** — semantic HTML, ARIA when needed\n\n---\n\n## Phase 4: State Management Decision Framework\n\n### State Type Decision Tree\n\n```\nIs it server data (from API)?\n├─ YES → TanStack Query (or SWR) — NEVER Redux/Zustand for server state\n│\n└─ NO → Is it shared across features?\n ├─ YES → Is it complex with many actions?\n │ ├─ YES → Zustand (or Redux Toolkit if team knows it)\n │ └─ NO → Jotai (atomic) or Zustand (simple store)\n │\n └─ NO → Is it shared within a feature?\n ├─ YES → Context + useReducer (or Zustand feature store)\n └─ NO → useState / useReducer (component-local)\n```\n\n### State Management Comparison\n\n| Tool | Best For | Bundle | Learning | Team Size |\n|------|----------|--------|----------|-----------|\n| useState | Component-local | 0 KB | None | Any |\n| useReducer | Complex local state | 0 KB | Low | Any |\n| Context | Feature-scoped, low-frequency | 0 KB | Low | Any |\n| Zustand | Global client state | 1.1 KB | Low | Any |\n| Jotai | Atomic derived state | 3.4 KB | Medium | Small-Med |\n| TanStack Query | Server state | 12 KB | Medium | Any |\n| Redux Toolkit | Complex global + middleware | 11 KB | High | Large |\n\n### Server State with TanStack Query\n\n```tsx\n// api/users.ts — query key factory pattern\nexport const userKeys = {\n all: ['users'] as const,\n lists: () => [...userKeys.all, 'list'] as const,\n list: (filters: Filters) => [...userKeys.lists(), filters] as const,\n details: () => [...userKeys.all, 'detail'] as const,\n detail: (id: string) => [...userKeys.details(), id] as const,\n}\n\n// hooks/useUsers.ts\nexport function useUsers(filters: Filters) {\n return useQuery({\n queryKey: userKeys.list(filters),\n queryFn: () => fetchUsers(filters),\n staleTime: 5 * 60 * 1000, // 5 min\n placeholderData: keepPreviousData,\n })\n}\n\nexport function useUpdateUser() {\n const queryClient = useQueryClient()\n return useMutation({\n mutationFn: updateUser,\n onMutate: async (newUser) => {\n // Optimistic update\n await queryClient.cancelQueries({ queryKey: userKeys.detail(newUser.id) })\n const previous = queryClient.getQueryData(userKeys.detail(newUser.id))\n queryClient.setQueryData(userKeys.detail(newUser.id), newUser)\n return { previous }\n },\n onError: (err, newUser, context) => {\n queryClient.setQueryData(userKeys.detail(newUser.id), context?.previous)\n },\n onSettled: (data, err, variables) => {\n queryClient.invalidateQueries({ queryKey: userKeys.detail(variables.id) })\n queryClient.invalidateQueries({ queryKey: userKeys.lists() })\n },\n })\n}\n```\n\n### Client State with Zustand\n\n```tsx\n// stores/useUIStore.ts — thin, focused stores\ninterface UIStore {\n sidebarOpen: boolean\n theme: 'light' | 'dark' | 'system'\n toggleSidebar: () => void\n setTheme: (theme: UIStore['theme']) => void\n}\n\nexport const useUIStore = create()(\n persist(\n (set) => ({\n sidebarOpen: true,\n theme: 'system',\n toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),\n setTheme: (theme) => set({ theme }),\n }),\n { name: 'ui-preferences' }\n )\n)\n\n// Usage: const theme = useUIStore((s) => s.theme) — always use selectors!\n```\n\n### 5 State Management Rules\n1. **Server state ≠ client state** — never mix them in the same store\n2. **Smallest scope possible** — useState > Context > Zustand > Redux\n3. **No useEffect for derived state** — use useMemo or compute inline\n4. **Selectors always** — `useStore(s => s.field)` not `useStore()`\n5. **URL is state** — search params, filters, pagination → URL, not React state\n\n---\n\n## Phase 5: Hooks Engineering\n\n### Custom Hook Template\n\n```tsx\n// hooks/useDebounce.ts\nexport function useDebounce(value: T, delayMs: number = 300): T {\n const [debouncedValue, setDebouncedValue] = useState(value)\n\n useEffect(() => {\n const timer = setTimeout(() => setDebouncedValue(value), delayMs)\n return () => clearTimeout(timer)\n }, [value, delayMs])\n\n return debouncedValue\n}\n```\n\n### Essential Custom Hooks Library\n\n| Hook | Purpose | When to Use |\n|------|---------|-------------|\n| `useDebounce` | Debounce value changes | Search inputs, resize |\n| `useMediaQuery` | Responsive breakpoints | Conditional rendering |\n| `useLocalStorage` | Persistent local state | Preferences, drafts |\n| `useIntersection` | Viewport detection | Lazy load, infinite scroll |\n| `usePrevious` | Track previous value | Animations, comparisons |\n| `useClickOutside` | Detect outside clicks | Dropdowns, modals |\n| `useEventListener` | Safe event binding | Keyboard, scroll, resize |\n| `useToggle` | Boolean state toggle | Modals, accordions |\n\n### Hook Rules (beyond React's rules)\n1. **One concern per hook** — `useUserSearch` not `useEverything`\n2. **Return tuple or object** — tuple for 1-2 values, object for 3+\n3. **Accept options object** — `useDebounce(value, { delay: 300 })` scales better\n4. **Handle cleanup** — every subscription/timer needs cleanup in useEffect return\n5. **No hooks in conditions** — extract conditional logic into the hook body\n6. **Test hooks independently** — use `renderHook` from testing-library\n\n---\n\n## Phase 6: TypeScript Integration\n\n### Strict Configuration\n\n```json\n{\n \"compilerOptions\": {\n \"strict\": true,\n \"noUncheckedIndexedAccess\": true,\n \"noImplicitOverride\": true,\n \"exactOptionalPropertyTypes\": true,\n \"forceConsistentCasingInFileNames\": true,\n \"paths\": {\n \"@/*\": [\"./src/*\"]\n }\n }\n}\n```\n\n### Essential Type Patterns\n\n```tsx\n// 1. Discriminated unions for state machines\ntype AsyncState =\n | { status: 'idle' }\n | { status: 'loading' }\n | { status: 'success'; data: T }\n | { status: 'error'; error: Error }\n\n// 2. Polymorphic components\ntype ButtonProps = {\n as?: C\n variant?: 'primary' | 'secondary'\n} & ComponentPropsWithoutRef\n\nexport function Button({\n as,\n variant = 'primary',\n ...props\n}: ButtonProps) {\n const Component = as || 'button'\n return \n}\n\n// 3. Branded types for IDs\ntype UserId = string & { __brand: 'UserId' }\ntype PostId = string & { __brand: 'PostId' }\n\n// 4. Zod for runtime validation\nconst userSchema = z.object({\n id: z.string().uuid(),\n email: z.string().email(),\n role: z.enum(['admin', 'user', 'viewer']),\n})\ntype User = z.infer\n```\n\n### 5 TypeScript Rules\n1. **Zero `any`** — use `unknown` and narrow, or generics\n2. **Zod at boundaries** — validate all external data (API, forms, URL params)\n3. **Discriminated unions over optional fields** — `{ status: 'success'; data: T }` not `{ data?: T; error?: Error }`\n4. **Branded types for IDs** — prevent `userId` being passed where `postId` expected\n5. **Satisfies over as** — `config satisfies Config` preserves inference; `as Config` lies\n\n---\n\n## Phase 7: Performance Optimization\n\n### Performance Budget\n\n| Metric | Target | Measurement |\n|--------|--------|-------------|\n| First Contentful Paint | < 1.8s | Lighthouse |\n| Largest Contentful Paint | < 2.5s | Lighthouse |\n| Interaction to Next Paint | < 200ms | Lighthouse |\n| Cumulative Layout Shift | < 0.1 | Lighthouse |\n| Bundle size (gzipped) | < 200 KB | webpack-bundle-analyzer |\n| JS execution (main thread) | < 3s | Chrome DevTools |\n\n### Optimization Priority Stack\n\n| Priority | Technique | Impact | Effort |\n|----------|-----------|--------|--------|\n| P0 | Code splitting (route-based) | 🔴 High | Low |\n| P0 | Image optimization (next/image, srcset) | 🔴 High | Low |\n| P1 | Tree shaking (named imports) | 🟡 Medium | Low |\n| P1 | Virtualization for long lists | 🟡 Medium | Medium |\n| P1 | Debounce expensive operations | 🟡 Medium | Low |\n| P2 | React.memo on expensive components | 🟢 Low-Med | Low |\n| P2 | useMemo/useCallback for expensive calculations | 🟢 Low-Med | Low |\n| P3 | Web Workers for heavy computation | 🟢 Low | High |\n\n### Code Splitting Patterns\n\n```tsx\n// 1. Route-based (automatic with Next.js, manual with React Router)\nconst Dashboard = lazy(() => import('./features/dashboard'))\nconst Settings = lazy(() => import('./features/settings'))\n\n// 2. Component-based (heavy components)\nconst Chart = lazy(() => import('./components/Chart'))\nconst MarkdownEditor = lazy(() =>\n import('./components/MarkdownEditor').then(m => ({ default: m.MarkdownEditor }))\n)\n\n// 3. Library-based (heavy third-party)\nconst { PDFViewer } = await import('@react-pdf/renderer')\n```\n\n### React Compiler (React 19+)\n```tsx\n// With React Compiler enabled, manual memo/useMemo/useCallback become unnecessary\n// The compiler auto-memoizes. Remove manual optimizations:\n// ❌ const memoized = useMemo(() => expensiveCalc(data), [data])\n// ✅ const memoized = expensiveCalc(data) // compiler handles it\n\n// Enable in babel config:\n// plugins: [['babel-plugin-react-compiler', {}]]\n```\n\n### Rendering Performance Rules\n1. **Never create components inside components** — define at module level\n2. **Never create objects/arrays in JSX** — `style={{ color: 'red' }}` rerenders always\n3. **Children as props prevent rerender** — ``\n4. **Key must be stable and unique** — not index, not `Math.random()`\n5. **Avoid context value churn** — memoize provider value or split contexts\n6. **Profile before optimizing** — React DevTools Profiler, not guesswork\n\n---\n\n## Phase 8: Error Handling & Resilience\n\n### Error Boundary Architecture\n\n```tsx\n// Three levels of error boundaries:\n// 1. App-level (catches everything, shows full-page error)\n// 2. Feature-level (isolates feature failures)\n// 3. Component-level (for risky widgets — charts, third-party)\n\n// Modern error boundary with react-error-boundary\nimport { ErrorBoundary, FallbackProps } from 'react-error-boundary'\n\nfunction FeatureErrorFallback({ error, resetErrorBoundary }: FallbackProps) {\n return (\n \n
Something went wrong
\n
{error.message}\n
\n