# Profiling a React Native app

Exact recording steps per tool. Open this when you need a number and the user does not know how to capture one.

Sources: https://reactnative.dev/docs/react-native-devtools · https://reactnative.dev/docs/profiling · https://docs.expo.dev/debugging/tools/

## 1. Perf Monitor — 30 seconds, always first

Open the Dev Menu (shake the device, or `m` in the bundler terminal) → **Show Perf Monitor**. Reproduce the slow scenario and read the two frame rates:

| Reading | Meaning | Where to look next |
|---|---|---|
| JS FPS drops, UI FPS holds | Your JavaScript blocks the thread | DevTools Performance panel, React Profiler |
| UI FPS drops, JS FPS holds | Native rendering: too many views, shadows, overdraw, large images | Android Studio system trace / Instruments |
| Both drop | Usually a huge re-render producing a huge native update | Start with the JS side |

The same overlay shows RAM and view counts — a view count that climbs on every scroll means rows are not being recycled.

## 2. React Native DevTools

Press **`j`** in the terminal running the bundler (or Dev Menu → *Open DevTools*). Panels:

- **Performance** (RN 0.83+): record the interaction, read JavaScript execution alongside React performance tracks, network events and user timings. The longest task is the one to fix.
- **React Components**: inspect the tree, enable re-render highlighting to see which subtree updates on every keystroke or scroll frame.
- **React Profiler**: record → interact → stop; read the slowest commit and why each component rendered.
- **Memory**: heap snapshots (see §5).
- **Network** (RN 0.83+): `fetch`, `XMLHttpRequest` and `<Image>` requests, with timings — often the real cause of "the screen is slow".

Profiles from DevTools are not symbolicated against release source maps, so use DevTools to find *what* is slow in development and native traces to confirm the cost on a release build.

## 3. Android: system trace on a release-like build

1. Build the app as **profileable** (or a release build with profiling enabled) and turn development mode off.
2. Android Studio → Profiler → **Capture System Activities**.
3. Record the scenario, stop, then *Past Recordings* → **Export recording**.
4. Open the trace in [Perfetto](https://perfetto.dev/): look at the main thread, the RN JS thread, and frame timelines. Long main-thread slices during scroll are native rendering cost; long JS-thread slices are yours.

For native CPU hotspots use *Find CPU Hotspots (Java/Kotlin Recording)* and open the export in the Firefox Profiler.

Cold start, repeated five times with the app force-stopped in between:

```bash
adb shell am force-stop com.example.app
adb shell am start -W com.example.app/.MainActivity   # read TotalTime
```

## 4. iOS: Instruments

Xcode → Product → Profile (release configuration):

- **App Launch** for cold start breakdown.
- **Core Animation / Animation Hitches** for dropped frames, with the device unplugged from the debugger where possible.
- **Time Profiler** for main-thread hotspots; **Allocations** and **Leaks** for memory.

Always test on the oldest supported device. A current-generation phone hides everything that matters.

## 5. Memory

DevTools → Memory → heap snapshot on the suspect screen. Navigate away and back five times, snapshot again, compare and sort by retained size. Growth that never returns points to a subscription, timer or cache that outlives the screen.

For native memory (images, native modules) use Android Studio's Memory Profiler or Instruments Allocations; a JS heap that is flat while total memory climbs means the leak is native, usually decoded images.

## 6. Time-to-interactive marks

Instrument the moments that matter rather than guessing:

```ts
// shared/lib/timing.ts
const marks = new Map<string, number>();
export function mark(name: string) { marks.set(name, Date.now()); }
export function measure(from: string, to: string) {
  const a = marks.get(from), b = marks.get(to);
  if (a && b) analytics.track('timing', { name: `${from}→${to}`, ms: b - a });
}
```

Mark app start (module scope of the root layout), splash hidden, first screen data resolved, and first interaction possible. Report the deltas from real devices; the field distribution matters more than your laptop's simulator.

## 7. Reporting a profile

State the device, OS, build type, Expo SDK, the exact scenario, how many repetitions, and the number with its spread. A profile without these cannot be compared to the one taken after the fix — and an uncomparable profile is not evidence.
