/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

**(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 is busy, native animations keep running (they're on the UI thread), but React updates stall.

import { InteractionManager } f