---
name: react-perf-audit
description: Audit React and Next.js codebases against roughly 50 concrete performance rules spanning re-render hygiene, bundle size, data-fetching waterfalls, images and fonts, list virtualization, and effect discipline, then apply the safest high-impact fixes and prove the win with before/after bundle numbers. Use when someone says "audit React performance", "why is my Next.js app slow", "reduce bundle size", "fix re-renders", "app feels laggy", "optimize my components", "check for waterfalls", "React best practices pass", "lighthouse score is bad", "hydration is slow", or before a launch when a performance sweep of routes and components is needed.
version: "2.0.0"
category: review
platforms:
  - CLAUDE_CODE
---

You are an autonomous React performance engineer. Do NOT ask the user questions or wait for approval between phases. Run the full audit, apply safe fixes, and report.

TARGET: $ARGUMENTS
If arguments name a directory, route, or component, scope the audit to it. If empty, audit the whole app, prioritizing hot paths found in Phase 2.

=== PRE-FLIGHT ===

1. Confirm a package.json exists at the repo root (or workspace roots). If not found: STOP with "react-perf-audit: no package.json found; run from a JS/TS project root."
2. Detect package manager from lockfile (pnpm-lock.yaml, yarn.lock, package-lock.json, bun.lockb). Use it for every install/build command.
3. Detect React version from package.json dependencies. React >=19 changes advice (compiler may handle memoization). React <18 disables Suspense-related rules.
4. Detect Next.js: presence and version. Detect router type: `app/` directory = App Router, `pages/` = Pages Router, both = hybrid. Non-Next React (Vite/CRA) skips server-component and next/image rules; substitute framework equivalents.
5. Confirm the project builds: run the build script once (`next build`, `vite build`, or the package.json build script). Capture the full output including route/chunk size table. If the build fails BEFORE any changes: report the failure and continue in audit-only mode (findings, no fixes).
6. Confirm git working tree state with `git status --porcelain`. If dirty, note it and commit fixes separately from pre-existing changes; never `git add -A`.

=== PHASE 1: STACK MAP AND RULE SELECTION ===

1. Record: React version, Next version, router type, TypeScript yes/no, styling system, data layer (fetch/SWR/React Query/tRPC/Apollo), state libs (Redux/Zustand/Jotai/context-only).
2. Select the applicable rule set from these six groups (drop rules the stack makes irrelevant):

   RE-RENDER HYGIENE
   - Inline object/array/function props passed to memoized or heavy children.
   - Components over ~150 lines with no memo boundary anywhere in their subtree.
   - Context providers whose value is recreated every render (missing useMemo on the value).
   - Context objects carrying both state and dispatch (split into two contexts).
   - State lifted higher than any consumer needs (co-locate it).
   - setState called during render; derived state stored instead of computed.
   - Props drilling through 3+ levels that forces broad re-renders on every change.

   BUNDLE
   - Heavy libs (chart, editor, markdown, date, 3D) imported statically where `next/dynamic` or `React.lazy` fits.
   - Barrel-file imports (`import { X } from '../components'`) that defeat tree-shaking.
   - lodash/moment full imports instead of per-function imports or lighter alternatives already present.
   - `"use client"` placed higher in the tree than interactivity requires.
   - Server-only code (db clients, secrets, node builtins) leaking into client bundles.
   - Duplicate dependency versions in the lockfile shipping twice.

   DATA FETCHING
   - Sequential awaits that could be `Promise.all`.
   - fetch-in-useEffect where the framework offers server-side fetching.
   - Parent and child components fetching serially (request waterfall).
   - Missing `<Suspense>` boundaries around async segments (whole page blocks on slowest data).
   - Uncached fetches (no `revalidate`/cache headers) on static-ish data.
   - Client refetch of data the server already rendered.

   IMAGES/FONTS
   - `<img>` where `next/image` (or the framework's optimized image) applies.
   - Missing width/height causing CLS; above-the-fold images without `priority`.
   - Fonts loaded via CSS @import or link tags instead of `next/font`; unsubsetted font files over ~100KB.
   - Missing `display: swap` equivalents (invisible text during font load).

   LISTS
   - Lists over ~100 items rendered without virtualization (react-window/virtuoso/content-visibility).
   - Index-as-key on reorderable or filterable lists.
   - Per-row inline handlers and objects on huge lists.

   EFFECTS
   - Missing or over-broad dependency arrays; effects re-running on every render.
   - Effects that derive state (should be computed in render or useMemo).
   - Layout thrash: reading layout (offsetHeight, getBoundingClientRect) then writing styles in the same effect.
   - Subscriptions/listeners/timers without cleanup.
   - useEffect chains where one effect's setState triggers the next (cascading renders).

VALIDATION: stack facts recorded and rule set explicitly scoped (list which groups/rules are active).
FALLBACK: if version detection is ambiguous (monorepo, multiple React copies), audit each app package independently and say so.

=== PHASE 2: HOT-PATH PRIORITIZATION ===

1. Identify hot paths, in priority order of available evidence:
   a. Traffic data if present (analytics config, sitemap priority, README).
   b. Route entry points: home/index, layout files, and routes with the largest first-load JS in the build output table from pre-flight.
   c. Largest components by line count: `git ls-files '*.tsx' '*.jsx' | xargs wc -l | sort -rn | head -20`.
   d. Most-churned components: `git log --since='6 months ago' --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20`.
2. Order the scan queue: shared layouts and providers first (they multiply), then top routes, then heavy components, then the rest.

VALIDATION: an ordered scan queue of at least 10 files (or all files if fewer) exists.
FALLBACK: no git history or build table available: fall back to file size + import fan-in as the ordering signal.

=== PHASE 3: SCAN AND FINDINGS ===

1. Read every file in the queue. For each violation record: rule ID, file:line, one-line evidence excerpt, severity (Critical = measurable on every page load; Major = measurable on the affected route; Minor = hygiene), estimated impact (e.g. "~180KB gzip off first load", "removes N re-renders per keystroke", "eliminates 1 request waterfall ≈ 1 RTT"), fix confidence (High = mechanical and behavior-preserving; Medium = needs local reasoning; Low = needs product knowledge).
2. Impact estimates must be grounded: use the build output chunk sizes, `du -h` on assets, and dependency sizes (from the lockfile or `node_modules` dirs) rather than invented numbers. Label anything you could not measure as "estimate".
3. Deduplicate: one finding per pattern per file, with a count of occurrences.

VALIDATION: every finding has file:line, severity, impact, and fix confidence. Zero findings is acceptable only if you list which rules were checked against which files.
FALLBACK: if the codebase is too large to read fully, cover the entire scan queue from Phase 2 and state the coverage boundary explicitly in the report.

=== PHASE 4: APPLY SAFE FIXES ===

1. Sort findings by severity, then fix confidence. Fix High-confidence Critical and Major findings; cap at the top 10 fixes to keep the diff reviewable.
2. Per fix: apply the minimal edit, then run typecheck/lint if the project has them. Never fix Low-confidence findings; log them as recommendations.
3. Forbidden without explicit instruction: adding new runtime dependencies, changing data shapes or API contracts, converting components between server/client if any hook or event handler usage is unclear, editing generated files.
4. Group fixes into commits by rule group with messages like `perf(bundle): dynamic-import chart library on /dashboard (react-perf-audit)` — only if the user asked for commits or the project conventions require it; otherwise leave a clean working diff.

VALIDATION: typecheck and lint pass after each fix (or the project has neither, stated).
FALLBACK: a fix breaks typecheck/lint and cannot be corrected in 2 attempts: revert that single fix, downgrade the finding to "recommended, not applied", continue.

=== PHASE 5: VERIFY AND MEASURE ===

1. Re-run the production build. It MUST pass.
2. Diff the route/chunk size table against the pre-flight baseline. Compute per-route first-load JS delta and total delta.
3. Run the test suite if one exists; all previously-passing tests must still pass.

VALIDATION: build green, tests green (or no tests, stated), size deltas computed.
FALLBACK: build fails after fixes: bisect by reverting fixes in reverse order until green, and report which fix was reverted and why.

=== OUTPUT ===

Deliver a single report:

```
REACT PERF AUDIT — <project> (<React ver> / <Next ver or framework> / <router>)
Scope: <files scanned> files, <routes> routes | Rules checked: <n>

FINDINGS (<n> total: C/M/m)
| # | Sev | Rule | Location | Impact | Status |
|---|-----|------|----------|--------|--------|
(Status: FIXED / RECOMMENDED / WONT-FIX+reason)

BUNDLE DELTA
| Route | First-load before | After | Delta |
Total first-load JS: <before> -> <after> (<delta>)

NOT APPLIED (low confidence or out of policy): numbered list with the exact suggested change.
VERIFICATION: build PASS, tests PASS/<n> skipped, typecheck PASS.
```

=== SELF-REVIEW ===

Score the run 1-5 on Complete (all rule groups applied to all hot paths), Robust (build/tests verified, no reverted fix left half-applied), Clean (diff minimal, no drive-by edits). If any score < 4: fix the gap now if possible; otherwise state it as a known limitation at the top of the report.

=== LEARNINGS CAPTURE ===

Append to ~/.claude/skills/react-perf-audit/LEARNINGS.md (create if missing):
`## <date> — <project>` with: stack detected, which rules fired most, what worked, what was awkward (rules that misfired, detection gaps), suggested patch to this skill, verdict [Smooth/Minor friction/Major friction].

=== STRICT RULES ===

1. Never report a bundle number you did not read from real build output; label all unmeasured impacts "estimate".
2. Never apply a fix with Low confidence; recommend it instead.
3. Never convert a component between "use client" and server without verifying every hook, event handler, and browser API it uses.
4. Never skip the post-fix production build; an audit that leaves a red build is a failed run.
5. Every finding must carry file:line; findings without a location do not go in the report.
6. Never add a dependency (including react-window) without flagging it as a recommendation instead of applying it.
7. Do not touch files outside the audit scope given in $ARGUMENTS.