JosiahSiegel/react-performance

React Performance Skill

Use this skill to diagnose and improve React rendering, bundle size, Web Vitals, list performance, image/media loading, state placement, and responsiveness with measurable before/after evidence.

When to Use This Skill

Use when the user asks for tasks covered by the frontmatter triggers, especially implementation guidance, debugging, architecture choices, production hardening, or performance-sensitive decisions in this domain. Start from this orchestrator, then load the focused reference file that matches the requested detail level.

Core Workflow

1. Measure first with React DevTools Profiler, Web Vitals, browser performance tools, or a bundle analyzer before changing code.
2. Identify the bottleneck class: unnecessary re-renders, expensive calculations, large lists, large bundles, slow interactions, image/media loading, or state placed too high.
3. Apply the smallest targeted fix: state colocation, composition, memoization, virtualization, lazy loading, dynamic import, or concurrent rendering APIs.
4. For media-heavy UIs, protect video element identity, avoid remounting, use refs for imperative controls, and lazy-load sources with IntersectionObserver.
5. Re-measure after each change and keep only optimizations that improve duration, Web Vitals, memory, decoder churn, or bundle size.

Key Gotchas

• Memoization has overhead; use React.memo, useMemo, and useCallback for measured hotspots or stable prop boundaries, not everywhere.
• Custom React.memo comparisons can be slower than rendering if they perform deep equality on large structures.
• Index keys in filtered/reordered lists can cause remounts and state loss, especially costly for video elements.
• Video elements are stateful browser resources; remounting can destroy hardware decoders and buffered playback state.
• Concurrent features improve responsiveness but do not make expensive work disappear; they schedule non-urgent work.

Reference Map

• references/react-performance-complete-guide.md - Full original guide covering measurement, memoization, code splitting, virtualization, render avoidance, concurrent features, images, bundles, media elements, decoder pools, and mobile video performance.
• references/virtualization-guide.md - Detailed virtualized-list guide already maintained for this skill.

Response Guidance

• Preserve the user's existing framework, library, and tooling choices unless there is a clear compatibility or performance reason to suggest an alternative.
• Give copy-pasteable code only for the exact task at hand; otherwise point to the relevant reference section.
• Call out tradeoffs, failure modes, and verification steps for production workflows.
• Prefer accessible, maintainable, measurable solutions over clever micro-optimizations.