/mobile-performance-react-native

name: mobile-performance-react-native
description: React Native performance profiling, optimization, and monitoring - JS/UI thread analysis, re-render prevention, list optimization, image performance, bundle size, startup time, memory leaks, React Compiler, New Architecture benefits

React Native Performance Patterns

> **Quick Guide:** Profile before optimizing -- use React Native DevTools Profiler (replaces Flipper since 0.76) and platform profilers to find actual bottlenecks. Target 60 FPS (16.67ms per frame). Understand JS thread vs UI thread: animations on the UI thread, business logic on JS. Use React.memo + useCallback for list items, FlashList for large lists, InteractionManager to defer heavy work during transitions. React Compiler (v1.0+) auto-memoizes most components -- verify before adding manual memoization. Always test in release builds; dev mode adds significant overhead.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST profile BEFORE optimizing -- use React Native DevTools Profiler or platform tools to identify actual bottlenecks, never optimize blindly)**

**(You MUST test performance in RELEASE builds -- dev mode adds significant overhead that masks real performance characteristics)**

**(You MUST understand the JS thread vs UI thread distinction -- animations belong on the UI thread, heavy computation must be deferred with InteractionManager)**

**(You MUST memoize renderItem callbacks and item components for FlashList/FlatList -- inline functions break virtualization performance)**

**(You MUST check if React Compiler is enabled before adding manual useMemo/useCallback/React.memo -- the compiler auto-memoizes and manual hints become redundant)**

</critical_requirements>

---

**Auto-detection:** React Native performance, FPS, frame rate, JS thread, UI thread, re-render, React.memo, useMemo, useCallback, FlashList optimization, FlatList optimization, InteractionManager, requestAnimationFrame, Hermes, bytecode, bundle size, Metro, tree shaking, startup time, memory leak, heap snapshot, React Compiler, auto-memoization, react-native-performance, Flipper profiler, React Native DevTools, Perf Monitor, useNativeDriver, LayoutAnimation, Reanimated worklet

**When to use:**

• Diagnosing dropped frames, jank, or slow transitions
• Optimizing list scrolling performance (FlashList/FlatList)
• Reducing re-renders in component trees
• Profiling JS thread vs UI thread bottlenecks
• Reducing app startup time or bundle size
• Detecting and fixing memory leaks
• Deciding whether to add manual memoization vs relying on React Compiler
• Monitoring performance in production

**When NOT to use:**

• General React Native component architecture (use the framework skill)
• Navigation setup and patterns (use the framework skill)
• Styling and theming patterns (use the framework skill)
• Animation API patterns (use the animation skill)

**Key patterns covered:**

• JS thread vs UI thread mental model and frame budget
• Profiling with React Native DevTools, platform profilers, and Hermes profiles
• Re-render optimization (React.memo, useCallback, useMemo, React Compiler)
• List optimization (FlashList cell recycling, FlatList tuning, memoized items)
• Image optimization (sizing, caching, preloading, placeholder strategies)
• Bundle size reduction (tree shaking, named imports, code splitting)
• Startup time optimization (Hermes bytecode, lazy loading, deferred work)
• Memory leak detection and prevention
• Production performance monitoring

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Re-render optimization, list performance, deferred work
• [examples/profiling.md](examples/profiling.md) - Profiling tools, memory analysis, production monitoring
• [reference.md](reference.md) - Decision frameworks, performance checklists, targets

---

<philosophy>

Philosophy

React Native performance optimization follows one principle: **measure first, optimize second**. Most performance issues stem from a small number of root causes -- unnecessary re-renders, JS thread congestion during animations, unoptimized lists, and memory leaks. Profiling identifies which of these is the actual problem.

**The threading model is key:**

• **JS Thread** -- Runs your React code, business logic, API calls, event handlers. When overloaded, UI updates are delayed and animations stutter.
• **UI Thread (Main Thread)** -- Renders native views, handles touch events, runs native animations. Must stay free for smooth 60 FPS.
• **Background Threads** -- Hermes GC, image decoding, network. These don't directly block the UI.

**Frame budget: 16.67ms.** Every frame must complete within this budget on both threads. A single dropped frame is perceptible; consistent drops create jank.

**The optimization hierarchy:**

1. **Architecture** -- New Architecture (Fabric + JSI) provides foundational performance gains. Enable it first. 2. **Algorithmic** -- Reduce work: fewer re-renders, smaller lists, deferred computation. 3. **Memoization** -- React Compiler handles most cases automatically. Add manual memoization only where profiling shows it helps. 4. **Native offloading** -- Move animations to the UI thread (useNativeDriver, animation library worklets), defer heavy work with InteractionManager.

**React Compiler changes the game:**

React Compiler (v1.0, stable since October 2025) auto-memoizes components, hooks, and values at build time. With React Compiler enabled, manual `useMemo`, `useCallback`, and `React.memo` are largely unnecessary. Check your project setup before adding manual memoization -- it may already be handled.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: JS Thread vs UI Thread Optimization

The most common performance issue is JS thread congestion during animations or transitions. When the JS thread i