React Optimizer

Audit a React codebase, report what is slow or fragile and why, agree a plan with the user, then fix it. Order: evidence, approval, edits. React "optimizations" (memoization, state moves, effect removal) can change behavior and hide bugs, so nothing is edited before the user approves.

Workflow

1. Scope (quick)

• Read package.json: React version, bundler (Vite/webpack/Parcel/CRA), router, state/data libs (Redux, Zustand, React Query, SWR, Apollo), UI kit, TypeScript, test runner, whether React Compiler or StrictMode is on. If next is a dependency, say so and hand off to nextjs-optimizer.
• Run python <skill-dir>/scripts/audit.py <project-root> -- static scan of package.json and .js/.jsx/.ts/.tsx (index keys, inline objects/functions in JSX props, effects that fetch or set state, missing cleanup, giant components, heavy imports, dangerouslySetInnerHTML, context value churn, no code splitting) with file:line evidence. --json for post-processing.
• Classify the pain: slow interactions (re-renders), slow load (bundle/network), memory growth (leaks), or code health. Ask which hurts if unclear.
• Read references/tooling.md once: what can actually be measured here (React DevTools Profiler, Lighthouse, bundle analyzer, why-did-you-render).

2. Audit

The script gives cheap leads; you find the rest by reading hot components. Read the app entry, router/layout, the 3-5 screens the user cares about, and any shared provider. Load only what applies:

Measure, never guess. Profile the interaction that is slow (React Profiler commit times, why each component rendered) and analyze the production bundle before editing. If the app can't be run or a tool is missing, say measurement wasn't possible instead of inventing numbers. Dev-mode timings are not representative; use a production build.

Mark each finding Confirmed (profile/code evidence) or Suspected (needs measuring).

3. Report

Fill assets/report-template.md, save as REACT_OPTIMIZATION_REPORT.md in the project root, and show the user. 5-line summary, findings table by impact/effort, then per-finding detail (evidence, why it hurts, fix, risk, behavior impact). Group related findings.

4. Plan -- then stop for approval

Use plan mode: EnterPlanMode (load with ToolSearch if deferred), write the plan, present with ExitPlanMode; if unavailable show it in chat and wait for an explicit "go". Structure:

1. Quick wins -- stable keys, route-level lazy, removing barrel/whole-library imports, lazy images, fixing effect cleanups. Low risk.
2. Structural -- moving state down, splitting contexts, replacing fetch-in-effect with a data library, virtualizing long lists, deleting derived-state effects. Name each behavior change.
3. Heavy -- React Compiler adoption, library swaps (moment, lodash, Redux), React/router major upgrades, SSR migration. Separately approved. Each step: files touched, expected effect, how to verify, how to roll back.

5. Fix

Only approved items, small groups. After each: typecheck (tsc --noEmit), lint, tests, build. A break must trace to one change. Don't mix a React version upgrade with optimization edits. Add memo/useMemo/useCallback only where a profile shows the render matters. If something turns out riskier than planned (changed behavior, public component API), stop and ask.

6. Verify and wrap up

Re-measure with the same scenario: Profiler commit duration and render counts for the interaction, bundle size (raw/gzip) per chunk, Lighthouse/Web Vitals on a production build. State plainly what could not be measured. End with deferred items and one suggested next step.

Principles

• Fix the structure before memoizing. Moving state down or lifting content up (children) removes renders for free; memo is a patch.
• Memoization needs a profile and stable props. One unstable prop defeats memo; useMemo on cheap work costs more than it saves.
• Effects are for syncing with external systems. Derived data, event reactions and fetching mostly don't belong there.
• Ship less JavaScript. Bundle size beats micro-optimizing renders for load time.
• Don't break correctness for speed. Keep keys, cleanups, a11y and error boundaries.
• Docs move. Check react.dev and the version in package.json, not memory (19 changed ref, use, Actions, Compiler).