react

What this skill does

# React Best Practices Audit

Focused audit layer for React and Next.js. Start with the six universal checks
— these are the highest-leverage bugs and appear in almost every codebase. Then
route to the reference that matches the user's specific question.

## Universal Checks (no exceptions — run these every time)

These six checks take seconds to scan for and catch the most common,
highest-impact mistakes. Skip them only if you have already verified them in
the same session.

1. **Components defined inside other components**
   They are re-created on every render. Their state resets. All memoization is
   lost. `React.memo` on them does nothing. Extract to module scope.

2. **Array index as `key` in dynamic lists**
   `key` is React's identity anchor. When the list reorders, inserts, or
   deletes, an index-based key reassigns identity to the wrong element — causing
   visual artifacts, wrong focus, and lost form state. Use a stable ID from the
   data. Exception: truly static, never-reordered lists where index is fine.

3. **Derived state via `useState` + `useEffect`**
   ```typescript
   // ❌ Two state variables + an Effect that syncs them
   const [filteredItems, setFilteredItems] = useState(items);
   useEffect(() => { setFilteredItems(items.filter(f)); }, [items, f]);

   // ✅ One variable, computed during render — no Effect, no lag
   const filteredItems = useMemo(() => items.filter(f), [items, f]);
   // or just: const filteredItems = items.filter(f); (if not expensive)
   ```

4. **Data fetching in `useEffect` without cleanup**
   Without cleanup, a slow request that resolves after a faster one will
   overwrite the fresh data with stale data (race condition):
   ```typescript
   // ❌ Race condition
   useEffect(() => {
     fetchUser(id).then(setUser);
   }, [id]);

   // ✅ Cleanup flag
   useEffect(() => {
     let ignore = false;
     fetchUser(id).then(data => { if (!ignore) setUser(data); });
     return () => { ignore = true; };
   }, [id]);

   // ✅ Best — use TanStack Query or RSC. Handles this automatically.
   ```

5. **Unmemoized Context provider value**
   Every time the parent re-renders, a new object reference is created, and
   every consumer re-renders even if the data hasn't changed:
   ```typescript
   // ❌ New object every parent render
   <UserContext.Provider value={{ user, login, logout }}>

   // ✅ Stable reference
   const value = useMemo(() => ({ user, login, logout }), [user, login, logout]);
   <UserContext.Provider value={value}>

   // ✅ Or split data and API into separate contexts (API never changes)
   <UserDataContext.Provider value={user}>
     <UserAPIContext.Provider value={api}> {/* stable — defined outside render */}
   ```

6. **Server Actions for client-side data reads**
   Server Actions serialize calls — they can't run in parallel. Using them for
   reads kills the performance of any page that needs multiple data sources:
   ```typescript
   // ❌ Server Action reads — serialize even under Promise.all
   const [user, posts] = await Promise.all([getUser(id), getPosts(id)]);
   // These still serialize because Server Actions are not parallelizable

   // ✅ Server Actions for mutations only. Reads via RSC, API routes,
   //    or TanStack Query.
   ```

7. **`React.FC` and `forwardRef` — both deprecated patterns**
   `React.FC` adds an implicit `children` prop (wrong in React 18+), forces a
   return type annotation, and provides no benefit over plain functions. In React
   19, `ref` is a regular prop — `forwardRef` still works but is unnecessary for
   new code:
   ```typescript
   // ❌ React.FC — adds noise, implies children, removed from CRA defaults
   const Button: React.FC<ButtonProps> = ({ label }) => <button>{label}</button>;

   // ✅ Plain function declaration
   function Button({ label }: ButtonProps) {
     return <button>{label}</button>;
   }

   // ❌ forwardRef — React 18 boilerplate, unnecessary in React 19+
   const Input = forwardRef<HTMLInputElement, InputProps>((props, ref) => (
     <input ref={ref} {...props} />
   ));

   // ✅ React 19 — ref as a plain prop
   function Input({ ref, ...props }: InputProps & { ref?: React.Ref<HTMLInputElement> }) {
     return <input ref={ref} {...props} />;
   }
   ```


## Priority Checklist (run after universal checks)

Use this for full audits. The six universal checks above catch the most common bugs;
this checklist catches the rest.

**CRITICAL — Eliminating Waterfalls:**
- [ ] No sequential awaits that could run in parallel
- [ ] `Promise.all` for independent operations
- [ ] API routes don't chain awaits unnecessarily
- [ ] Strategic Suspense boundaries for streaming

**CRITICAL — Bundle Size:**
- [ ] Direct imports (no barrel files)
- [ ] Dynamic imports for heavy components
- [ ] Conditional module loading
- [ ] Non-critical libs deferred
- [ ] Preload based on user intent

**HIGH — Server-Side Performance:**
- [ ] Server Actions have authentication
- [ ] RSC props minimized (only needed data)
- [ ] Parallel data fetching via composition
- [ ] `React.cache()` for per-request dedup
- [ ] `after()` for non-blocking operations
- [ ] No duplicate serialization

**MEDIUM-HIGH — Client Data Fetching:**
- [ ] SWR/TanStack Query for automatic deduplication
- [ ] Passive event listeners for scroll
- [ ] Global event listeners deduplicated
- [ ] `localStorage` versioned and minimal

**MEDIUM — Re-render Optimization:**
- [ ] Functional `setState` updates (no stale closures)
- [ ] Lazy state initialization for expensive values
- [ ] Narrow effect dependencies (primitives > objects)
- [ ] `useTransition` for non-urgent updates
- [ ] Derived state calculated during render (not via `useEffect`)
- [ ] Interaction logic in event handlers (not state + effect)
- [ ] `useRef` for transient values (mouse trackers, intervals)
- [ ] Extract to memoized components when re-render scope is too broad
- [ ] No unnecessary `useMemo` wrapping (prefer React Compiler if available)

**MEDIUM — Rendering Performance:**
- [ ] `content-visibility` for long lists
- [ ] `useTransition` over manual loading states
- [ ] Explicit conditional rendering (not `&&` with truthy non-booleans)
- [ ] `suppressHydrationWarning` for known server/client differences
- [ ] Prevent hydration mismatch without UI flicker

**LOW-MEDIUM — JavaScript Performance:**
- [ ] `Set`/`Map` for O(1) lookups
- [ ] Early returns in functions
- [ ] Cached repeated function calls
- [ ] `toSorted()` over `sort()` for immutability
- [ ] Avoid layout thrashing
- [ ] Hoist `RegExp` creation outside render

**LOW — Advanced Patterns:**
- [ ] Event handlers in refs for stable references
- [ ] `useEffectEvent` for stable callback refs
- [ ] App initialization with module-level guards (not `useEffect`)

## Report Format

For each violation:
```
[PRIORITY] Rule Name
File: path/to/file.tsx:line
Issue: [description of the problem]
Fix: [code example showing correct pattern]
```

After the full checklist, provide:
1. **Violation Count by Priority** — CRITICAL: N · HIGH: N · MEDIUM: N · LOW: N
2. **Top 3 Highest-Impact Fixes** — brief description + expected improvement
3. **Overall Assessment** — Pass / Needs Work / Critical Issues

## Stack Context — Determine Before Routing

Before loading references, determine which stack the user is on:

- **Next.js App Router** → RSC, Server Actions, streaming, and `react-19.md`
  action props / `useActionState` patterns apply
- **Vite SPA (React Router / TanStack Router)** → no RSC, TanStack Query is the
  primary data layer, `tanstack-query.md` is the first reference to reach for
- **Both** → `re-renders.md`, `useeffect-antipatterns.md`, `portals-and-stacking-context.md`,
  and `bundle-and-perf-investigation.md` are stack-agnostic

If unsure, look at the imports: `next/` imports → App Router; `react-router-dom`
or `@tanstack/react-router` → Vite SPA.

## References — Priority Table

Load the reference that matches the issue. Higher-priority references fix more
users / cause more dam