Diagnose and fix React Native and Expo performance by measuring first — slow cold start, dropped frames and janky FlashList scrolling, laggy gestures and animations, a blocked JS thread, long interactions, growing memory, and oversized JavaScript bundles or updates — with React Native DevTools, the Perf Monitor, Android Studio system traces, Perfetto, Instruments and Expo Atlas.
When agents use itUse this whenever the user says an Expo or React Native app is slow, stutters, drops frames, has low FPS, takes seconds to open, freezes while scrolling, or grows in memory or size; asks how to profile a device build, read a Hermes trace, or why a list or animation is janky. Also use it when an apparently slow screen turns out to be a data, image or re-render problem. For writing the screen use react-native-development; for web React use react-performance.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill react-native-performance -a github-copilot
# or with the org installer (adds .github/skills/react-native-performance):
npx -y github:AGCO-Global/org-skills add skill react-native-performance
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the frontend-react-native-skills plugin, which bundles all Frontend / React Native skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install frontend-react-native-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill react-native-performance -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill react-native-performance -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill react-native-performance -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill react-native-performance -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the react-native-performance folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
Two threads decide how the app feels: the JS thread runs your React code, the UI thread renders. Anything that blocks the JS thread beyond a frame budget drops frames, and almost every fix is moving work off that thread or doing less of it. Nothing here starts without a number from a release build on a real, slow device — a debug build on a simulator is five to ten times slower and hides the actual cause.
1. Decide first
Question
Default
Change when
Where to measure?
Release (or profileable) build on the oldest device you support
Reproducing a JS-only bug → a debug build is acceptable for the React Profiler, never for timings
Both fine but the app "feels" slow → it is a data or navigation-transition problem
Which tool?
React Native DevTools Performance panel (j in the bundler terminal)
Native-level cost → Android Studio system trace + Perfetto, or Instruments on iOS
Long list janks
FlashList v2 with small, memo-friendly rows and getItemType
Rows contain images or text measured per frame → fix the row, not the list
Animation janks
Reanimated 4 on the UI thread; CSS style props for simple transitions
It janks even on the UI thread → too many views or shadows; simplify the tree
Inactive tabs and screens cost
Leave them mounted
Off-screen screens re-render or hold heavy work → freezeOnBlur / enableFreeze(), or <Activity mode="hidden"> for a React subtree
Cold start too slow
Defer module side effects and non-critical init behind the splash
The bundle itself is huge → Expo Atlas, then remove or lazy-require the offenders
Still slow after the JS fixes
Look at the network and the images before adding more memoisation
Data arrives late → cache-first rendering with a persisted query cache
2. Measure: symptom → tool → number
Symptom
Tool
Capture
Slow cold start
adb shell am start -W <pkg>/.MainActivity (Android), Instruments App Launch (iOS), custom marks to first meaningful paint
TotalTime in ms, time to first interactive screen
Dropped frames scrolling or animating
Perf Monitor overlay (Dev Menu)
JS FPS vs UI FPS — which thread is starved
Slow interaction or render
React Native DevTools → Performance panel (JS execution + React tracks) and the React Profiler
Longest JS task, commit count per interaction
Native-level jank
Android Studio Profiler "Capture System Activities" on a profileable build → export → Perfetto; Instruments Core Animation on iOS
Main-thread work, GPU overdraw, layout passes
Memory growth
DevTools Memory panel heap snapshots; Android Studio / Xcode memory tools for native
Retained size across five screen visits
Bundle or update too big
EXPO_ATLAS=true npx expo export then npx expo-atlas .expo/atlas.jsonl
Largest modules and what pulled them in
Write the baseline down with device, OS, build type and the exact scenario. Profiles recorded in DevTools are not symbolicated in release builds, so pair them with native traces when you need release-only numbers. Recording steps: references/profiling.md.
3. Startup
Native bundles are monolithic: Expo Router async routes "do not support native production apps yet" and Suspense boundaries are disabled in native production bundles, so there is no route-level code splitting to buy. What you can defer is evaluation: inline require() at the point of use, inlineRequires in the Metro transformer (on in current templates — verify), and lazy singletons instead of module-scope work.
Hermes reads bytecode, so parse cost is near zero; the real startup cost is module side effects — analytics init, remote config, i18n loading, a store hydrating, a database migration.
Hold the native splash with expo-splash-screen until fonts, session and the first query are ready, then hide once. No flash of unstyled UI, no double render of the root.
Keep the root provider tree flat and free of fetches that block first paint. Measure again after each removal; startup work is usually three or four specific imports.
Evaluate Hermes V1 (SDK 55+) once dependencies allow — an engine-level win that costs no application code.
4. Lists, rendering and the JS thread
FlashList v2 measures automatically: estimatedItemSize and friends are ignored. Give it keyExtractor, getItemType when rows differ, and rows that take primitives so recycling is cheap.
Row hygiene decides list performance: no new Date(), Intl formatting, filter/sort or inline closures inside renderItem — pre-compute in the data layer. Images in rows need fixed dimensions, expo-image with recyclingKey, and a thumbnail URL, not the original.
Never nest a list inside a same-direction ScrollView; use ListHeaderComponent/ListFooterComponent.
The React re-render rules are shared with the web: move state down, split contexts, then memo — and with the React Compiler on by default since SDK 54 most manual memo in rows is unnecessary. The detailed tree is in the react-performance skill.
Flatten the view hierarchy: every View is a real native view. Fewer wrappers, fewer shadows (expensive on Android), no onLayout cascades that set state each frame.
Strip logging from release with babel-plugin-transform-remove-console; a console.log in a render path costs real milliseconds over the bridge-less serialiser too.
5. Animations, gestures and inactive screens
Animation runs on the UI thread or it janks: Reanimated 4 shared values and useAnimatedStyle, or CSS style props for simple transitions. The core Animated API and PanResponder are not options in new code.
Cross into React only on gesture end, with scheduleOnRN — runOnJS was renamed in Reanimated 4. A setState per frame is the single most common cause of gesture jank.
Complex drawing (charts, custom shapes) belongs in @shopify/react-native-skia rather than hundreds of Views.
Inactive screens still re-render on every state change. enableFreeze() from react-native-screens, or freezeOnBlur per screen, suspends hidden screens; <Activity mode="hidden"> does the same for a subtree you control. Both keep state and cost nothing while hidden.
6. Memory, network and size
Cleanups are not optional: AppState, Dimensions, Keyboard, NetInfo, event emitters, timers and in-flight requests all unsubscribe or abort on unmount. Unbounded in-memory maps of records or images need eviction.
Keep big binaries out of state: write them with expo-file-system and keep the URI.
Render from the persisted query cache first, then refetch; set staleTime deliberately so a tab switch does not trigger a network round trip.
Size: Expo Atlas for the JS bundle, R8/Proguard and .aab on Android, remove unused locales, icon sets and fonts. Updates ship as Hermes bytecode diffs from SDK 55 — roughly 75 % smaller — so keeping runtimeVersion stable across a release series is also a size decision.
7. Deliverable format
## Device & build
<model, OS version>, release build, Expo SDK <n>, Hermes, measured scenario
## Baseline
<metric>: <value> — tool used, repeated <n> times
## Findings (impact order)
1. <problem> — evidence (trace screenshot, FPS split, Atlas entry) — thread affected — expected gain
## Fixes
Minimal diff per finding, why it moves the number, risk
## Verify
Same device, same scenario: before → after. Guard added: <budget or test>
Checklist
Measured on a release or profileable build on a low-end physical device
JS FPS and UI FPS recorded separately before choosing a direction
Baseline repeated at least three times; the scenario is written down
Cold start measured with am start -W or launch instrumentation, not a stopwatch
Lists checked for row work, image sizes, getItemType, and no estimatedItemSize
Animations verified to run on the UI thread; no per-frame setState
Inactive screens frozen or unmounted where they were re-rendering
Effects with subscriptions and timers have cleanups; heap compared across repeated navigation
Bundle analysed with Expo Atlas before blaming the framework
The same measurement re-run after the fix, and the number quoted
Anti-patterns
Profiling a debug build on a simulator → release or profileable build, real device, dev mode off.
"It's obviously the list" → get JS vs UI FPS first; half of list jank is images or row formatting.
estimatedItemSize added to make FlashList faster → ignored in v2; fix the row instead.
runOnJS on every gesture update → scheduleOnRN once, on gesture end.
Trying to code-split native routes with React.lazy → native production bundles are monolithic; defer module side effects instead.
"Disable Hermes or the New Architecture to fix it" → neither is optional any more; fix the dependency.
Memoising everything after the compiler is already on → verify with the Profiler that a component is actually expensive.
Shipping a fix with no re-measurement → an unverified fix is a guess with extra code.
The shared React and React Native anti-pattern list lives in the react-development skill as react-anti-patterns.md.
Go deeper
references/profiling.md — opening React Native DevTools, the Performance panel workflow, Perf Monitor reading, Android Studio system trace to Perfetto, Instruments, heap snapshots, TTI marks.
references/startup-and-bundle.md — measuring cold start per platform, finding module side effects, splash handling, Expo Atlas walkthrough, binary and update size.
Sibling skills: react-native-development (implementing the fix), react-native-architecture (caching and release decisions), react-performance (the shared React re-render tree), react-native-testing, frontend-code-review.
---
name: react-native-performance
description: >
Diagnose and fix React Native and Expo performance by measuring first — slow cold start, dropped frames and
janky FlashList scrolling, laggy gestures and animations, a blocked JS thread, long interactions, growing
memory, and oversized JavaScript bundles or updates — with React Native DevTools, the Perf Monitor, Android
Studio system traces, Perfetto, Instruments and Expo Atlas. Use this whenever the user says an Expo or React
Native app is slow, stutters, drops frames, has low FPS, takes seconds to open, freezes while scrolling, or
grows in memory or size; asks how to profile a device build, read a Hermes trace, or why a list or animation
is janky. Also use it when an apparently slow screen turns out to be a data, image or re-render problem. For
writing the screen use react-native-development; for web React use react-performance.
metadata:
technology: React Native
type: performance
---
# React Native Performance
> **Targets:** React Native 0.87 · Expo SDK 54+ · Hermes · Reanimated 4 · FlashList v2 · **Verified:** 2026-09 against https://reactnative.dev, https://docs.expo.dev, https://docs.swmansion.com
Two threads decide how the app feels: the **JS thread** runs your React code, the **UI thread** renders. Anything that blocks the JS thread beyond a frame budget drops frames, and almost every fix is moving work off that thread or doing less of it. Nothing here starts without a number from a release build on a real, slow device — a debug build on a simulator is five to ten times slower and hides the actual cause.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Where to measure? | Release (or `profileable`) build on the oldest device you support | Reproducing a JS-only bug → a debug build is acceptable for the React Profiler, never for timings |
| Which thread? | Perf Monitor first: JS FPS low → your code; UI FPS low → native rendering, shadows, images, overdraw | Both fine but the app "feels" slow → it is a data or navigation-transition problem |
| Which tool? | React Native DevTools Performance panel (`j` in the bundler terminal) | Native-level cost → Android Studio system trace + Perfetto, or Instruments on iOS |
| Long list janks | FlashList v2 with small, memo-friendly rows and `getItemType` | Rows contain images or text measured per frame → fix the row, not the list |
| Animation janks | Reanimated 4 on the UI thread; CSS style props for simple transitions | It janks even on the UI thread → too many views or shadows; simplify the tree |
| Inactive tabs and screens cost | Leave them mounted | Off-screen screens re-render or hold heavy work → `freezeOnBlur` / `enableFreeze()`, or `<Activity mode="hidden">` for a React subtree |
| Cold start too slow | Defer module side effects and non-critical init behind the splash | The bundle itself is huge → Expo Atlas, then remove or lazy-`require` the offenders |
| Still slow after the JS fixes | Look at the network and the images before adding more memoisation | Data arrives late → cache-first rendering with a persisted query cache |
## 2. Measure: symptom → tool → number
| Symptom | Tool | Capture |
|---|---|---|
| Slow cold start | `adb shell am start -W <pkg>/.MainActivity` (Android), Instruments App Launch (iOS), custom marks to first meaningful paint | `TotalTime` in ms, time to first interactive screen |
| Dropped frames scrolling or animating | Perf Monitor overlay (Dev Menu) | JS FPS vs UI FPS — which thread is starved |
| Slow interaction or render | React Native DevTools → Performance panel (JS execution + React tracks) and the React Profiler | Longest JS task, commit count per interaction |
| Native-level jank | Android Studio Profiler "Capture System Activities" on a profileable build → export → Perfetto; Instruments Core Animation on iOS | Main-thread work, GPU overdraw, layout passes |
| Memory growth | DevTools Memory panel heap snapshots; Android Studio / Xcode memory tools for native | Retained size across five screen visits |
| Bundle or update too big | `EXPO_ATLAS=true npx expo export` then `npx expo-atlas .expo/atlas.jsonl` | Largest modules and what pulled them in |
Write the baseline down with device, OS, build type and the exact scenario. Profiles recorded in DevTools are not symbolicated in release builds, so pair them with native traces when you need release-only numbers. Recording steps: `references/profiling.md`.
## 3. Startup
- Native bundles are **monolithic**: Expo Router async routes "do not support native production apps yet" and Suspense boundaries are disabled in native production bundles, so there is no route-level code splitting to buy. What you can defer is *evaluation*: inline `require()` at the point of use, `inlineRequires` in the Metro transformer (on in current templates — verify), and lazy singletons instead of module-scope work.
- Hermes reads bytecode, so parse cost is near zero; the real startup cost is module side effects — analytics init, remote config, i18n loading, a store hydrating, a database migration.
- Hold the native splash with `expo-splash-screen` until fonts, session and the first query are ready, then hide once. No flash of unstyled UI, no double render of the root.
- Keep the root provider tree flat and free of fetches that block first paint. Measure again after each removal; startup work is usually three or four specific imports.
- Evaluate **Hermes V1** (SDK 55+) once dependencies allow — an engine-level win that costs no application code.
## 4. Lists, rendering and the JS thread
- FlashList v2 measures automatically: `estimatedItemSize` and friends are ignored. Give it `keyExtractor`, `getItemType` when rows differ, and rows that take primitives so recycling is cheap.
- Row hygiene decides list performance: no `new Date()`, `Intl` formatting, `filter`/`sort` or inline closures inside `renderItem` — pre-compute in the data layer. Images in rows need fixed dimensions, `expo-image` with `recyclingKey`, and a thumbnail URL, not the original.
- Never nest a list inside a same-direction `ScrollView`; use `ListHeaderComponent`/`ListFooterComponent`.
- The React re-render rules are shared with the web: move state down, split contexts, then memo — and with the React Compiler on by default since SDK 54 most manual `memo` in rows is unnecessary. The detailed tree is in the `react-performance` skill.
- Flatten the view hierarchy: every `View` is a real native view. Fewer wrappers, fewer shadows (expensive on Android), no `onLayout` cascades that set state each frame.
- Strip logging from release with `babel-plugin-transform-remove-console`; a `console.log` in a render path costs real milliseconds over the bridge-less serialiser too.
## 5. Animations, gestures and inactive screens
- Animation runs on the UI thread or it janks: Reanimated 4 shared values and `useAnimatedStyle`, or CSS style props for simple transitions. The core `Animated` API and `PanResponder` are not options in new code.
- Cross into React only on gesture end, with `scheduleOnRN` — `runOnJS` was renamed in Reanimated 4. A `setState` per frame is the single most common cause of gesture jank.
- Complex drawing (charts, custom shapes) belongs in `@shopify/react-native-skia` rather than hundreds of `View`s.
- Inactive screens still re-render on every state change. `enableFreeze()` from `react-native-screens`, or `freezeOnBlur` per screen, suspends hidden screens; `<Activity mode="hidden">` does the same for a subtree you control. Both keep state and cost nothing while hidden.
## 6. Memory, network and size
- Cleanups are not optional: `AppState`, `Dimensions`, `Keyboard`, `NetInfo`, event emitters, timers and in-flight requests all unsubscribe or abort on unmount. Unbounded in-memory maps of records or images need eviction.
- Keep big binaries out of state: write them with `expo-file-system` and keep the URI.
- Render from the persisted query cache first, then refetch; set `staleTime` deliberately so a tab switch does not trigger a network round trip.
- Size: Expo Atlas for the JS bundle, R8/Proguard and `.aab` on Android, remove unused locales, icon sets and fonts. Updates ship as Hermes bytecode diffs from SDK 55 — roughly 75 % smaller — so keeping `runtimeVersion` stable across a release series is also a size decision.
## 7. Deliverable format
```
## Device & build
<model, OS version>, release build, Expo SDK <n>, Hermes, measured scenario
## Baseline
<metric>: <value> — tool used, repeated <n> times
## Findings (impact order)
1. <problem> — evidence (trace screenshot, FPS split, Atlas entry) — thread affected — expected gain
## Fixes
Minimal diff per finding, why it moves the number, risk
## Verify
Same device, same scenario: before → after. Guard added: <budget or test>
```
## Checklist
- [ ] Measured on a release or profileable build on a low-end physical device
- [ ] JS FPS and UI FPS recorded separately before choosing a direction
- [ ] Baseline repeated at least three times; the scenario is written down
- [ ] Cold start measured with `am start -W` or launch instrumentation, not a stopwatch
- [ ] Lists checked for row work, image sizes, `getItemType`, and no `estimatedItemSize`
- [ ] Animations verified to run on the UI thread; no per-frame `setState`
- [ ] Inactive screens frozen or unmounted where they were re-rendering
- [ ] Effects with subscriptions and timers have cleanups; heap compared across repeated navigation
- [ ] Bundle analysed with Expo Atlas before blaming the framework
- [ ] The same measurement re-run after the fix, and the number quoted
## Anti-patterns
- **Profiling a debug build on a simulator** → release or profileable build, real device, dev mode off.
- **"It's obviously the list"** → get JS vs UI FPS first; half of list jank is images or row formatting.
- **`estimatedItemSize` added to make FlashList faster** → ignored in v2; fix the row instead.
- **`runOnJS` on every gesture update** → `scheduleOnRN` once, on gesture end.
- **Trying to code-split native routes with `React.lazy`** → native production bundles are monolithic; defer module side effects instead.
- **"Disable Hermes or the New Architecture to fix it"** → neither is optional any more; fix the dependency.
- **Memoising everything after the compiler is already on** → verify with the Profiler that a component is actually expensive.
- **Shipping a fix with no re-measurement** → an unverified fix is a guess with extra code.
- The shared React and React Native anti-pattern list lives in the `react-development` skill as `react-anti-patterns.md`.
## Go deeper
- `references/profiling.md` — opening React Native DevTools, the Performance panel workflow, Perf Monitor reading, Android Studio system trace to Perfetto, Instruments, heap snapshots, TTI marks.
- `references/startup-and-bundle.md` — measuring cold start per platform, finding module side effects, splash handling, Expo Atlas walkthrough, binary and update size.
- Sibling skills: `react-native-development` (implementing the fix), `react-native-architecture` (caching and release decisions), `react-performance` (the shared React re-render tree), `react-native-testing`, `frontend-code-review`.