react-optimizer

---
name: react-optimizer
description: Audit and optimize React apps and component libraries (Vite, CRA, Remix, Parcel, Expo web, plain SPAs; React 17-19) for render performance, bundle size, load speed, Core Web Vitals, state and data-fetching design, accessibility basics, and code safety, with real before/after measurement. Always produces a written findings report and a fix plan for approval before touching any code. Use this whenever the user mentions a slow or laggy React app, too many re-renders, large bundle, slow first load, memo/useMemo/useCallback questions, React Profiler, context or Redux performance, list virtualization, useEffect bugs or fetch waterfalls, React Compiler adoption, or "optimize my React code" -- even if they don't say "audit". For Next.js projects prefer the nextjs-optimizer skill.
---

# 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:

| Area                                                       | Reference                       |
| ---------------------------------------------------------- | ------------------------------- |
| Re-renders, memo, keys, lists, transitions, React Compiler | `references/rendering.md`       |
| State placement, context, stores, derived state            | `references/state.md`           |
| Effects, data fetching, waterfalls, Suspense, caching      | `references/effects-data.md`    |
| Bundle size, code splitting, images, CWV, build config     | `references/bundle-loading.md`  |
| Accessibility, XSS, types, tests, deps, library authoring  | `references/safety-quality.md`  |
| Profiler, analyzers, honest measurement                    | `references/tooling.md`         |

**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).

• LICENSE 1 KB
• README.md 1 KB
• SKILL.md 6 KB
• assets/report-template.md 1 KB
• references/bundle-loading.md 3 KB
• references/effects-data.md 2 KB
• references/rendering.md 3 KB
• references/safety-quality.md 2 KB
• references/state.md 2 KB
• references/tooling.md 2 KB
• scripts/audit.py 10 KB