Summary
This skill turns “the app feels slow/janky” into a measured, repeatable, and shippable optimisation program for Expo-managed React Native apps.
Non‑negotiables:
- Optimise against user-visible KPIs (startup/TTI, scroll FPS, navigation responsiveness, memory growth, p95 network latency).
- Profile in production-like builds (release / profile / debugOptimized) — not in dev mode.
- Make one change at a time, re-measure, and keep a rollback path.
When to use
Use when you need to:
- Fix slow startup, “white screen”, or delayed time-to-interactive.
- Fix scroll jank, dropped frames, sluggish taps, or slow transitions.
- Reduce memory growth, crashes under pressure, or image/video bloat.
- Reduce OTA update size, JS bundle size, or Android binary size.
- Add regression prevention: perf budgets + CI gates + production monitoring.
When NOT to use
Don’t use this skill to:
- Prematurely micro-optimise already-smooth screens with no KPI regression.
- Make changes without a reproducible scenario and a baseline.
- “Optimise” by switching libraries blindly (measure first).
Inputs
- Repo (Expo managed or CNG/prebuild), ideally with:
package.json
app.json / app.config.*
metro.config.js (if present)
babel.config.*
eas.json (if using EAS)
- A concrete report of the problem:
- Device(s), OS versions, and which flow feels slow.
- Steps to reproduce (or a screen name if using Expo Router).
If details are missing, infer as much as possible from the repo and propose a minimal repro script.
Outputs
Deliver both:
- Perf audit report (see template in
assets/templates/perf-audit-report-template.md):
- KPIs + budgets
- Baseline measurements (device + build type)
- Root cause hypothesis + evidence
- Fix plan (ordered by ROI / risk)
- Before/after measurements
- Code changes (PR-ready) implementing the top fixes, plus:
- Updated perf budgets (if needed)
- CI gate(s) for bundle/update size at minimum
Tooling assumptions
You can use:
- Expo CLI (
npx expo …), EAS CLI (eas …) where available.
- React Native DevTools (Performance + Memory panels) for JS-level analysis.
- Native profilers (Android Studio, Xcode Instruments) for CPU/memory/UI tracing.
You should prefer:
- Release/profile builds for measurement.
- Same device class and same scenario script for before/after.
The optimisation workflow (high level)
- Define KPIs + budgets (3–6 metrics max). Pick what users feel.
- Create a repeatable scenario (startup, list scroll, key navigation, etc.).
- Measure baseline in a production-like build.
- Classify the bottleneck domain:
- Startup/bundle
- JS thread
- UI thread
- Lists/images
- Memory
- Network/background
- Apply targeted fixes (smallest change, highest ROI first).
- Re-measure. Keep only changes with KPI wins.
- Add regression control (budgets + CI gates + monitoring).
Detailed playbook
Phase 0 — Establish reality (no guesswork)
0.1 Identify versions and architecture
- Expo SDK version, React Native version, React version.
- New Architecture status (mandatory in newer SDKs).
- JS engine (Hermes/JSC/V8), OTA updates usage (
expo-updates).
- Major perf-sensitive libs: navigation (Expo Router/React Navigation), lists (FlashList), animation (Reanimated), images (
expo-image).
0.2 Choose KPIs (pick 3–6)
Suggested defaults:
- Cold start: time-to-first-render and/or time-to-interactive
- Scroll: dropped frames / FPS on the heaviest list
- Navigation: p95 screen transition time for a representative flow
- Memory: steady-state RSS after repeating a navigation loop 5–10×
- Network: p95 API latency on a key endpoint
Record budgets as numbers (not “fast”). See references/00-principles-and-kpis.md.
0.3 Choose build type for measuring
- Prefer store-equivalent Release.
- If you need debuggability, use Android “profileable” builds, iOS Instruments, or Expo’s
debugOptimized where applicable.
Phase 1 — Baseline measurement (release-build discipline)
1.1 Baseline checklist (must pass)
- Dev mode off.
- No remote JS debugging.
- Same device, same OS version, same network conditions.
- Warm vs cold start explicitly noted.
1.2 Capture traces and numbers
- React Native DevTools:
- Performance trace (JS execution + React tracks + network events)
- Heap snapshot (if memory suspected)
- Native tools:
- Android Studio System Trace for jank attribution
- Xcode Instruments (Time Profiler / Allocations / Leaks)
Store raw artefacts (trace files, screenshots) alongside your report.
Phase 2 — Decide the bottleneck domain
Use this decision rubric:
- Startup slow: long splash, white screen, slow first render → startup/bundle.
- Taps lag / transitions slow but scrolling OK → JS thread or navigation.
- Scroll stutters even with little JS work → UI thread or list/render cost.
- Memory climbs over time → leak / image/video pressure.
- Everything waits on API → network/caching.
Phase 3 — Apply high-ROI fixes by domain
A) Startup & bundle
Do in this order:
- Stop doing work before first paint
- Gate only critical assets (fonts, tiny config) and hide splash ASAP.
- Confirm Hermes
- Make it explicit in app config if necessary.
- If you use OTA updates, ensure runtime compatibility when engine/bytecode changes.
- Shrink JS evaluation
- Prefer ESM imports, avoid breaking tree shaking.
- Consider Metro
inlineRequires (validate side effects!).
- Control OTA payloads
- Configure update asset inclusion/exclusion and verify assets.
- Android size knobs (measure trade-offs)
- Enable R8 minify + resource shrinking.
- Treat bundle compression as a measured toggle (smaller APK vs slower startup).
See references/02-startup-bundle-ota.md.
B) JS thread stalls (renders + computation)
High ROI:
- Remove production
console.*.
- Defer heavy work with
InteractionManager / requestAnimationFrame.
- Reduce re-renders:
- Stabilise props, split context, memoise hot rows.
- Consider React Compiler (branch rollout + profiling + easy rollback).
See references/03-rendering-js-ui.md.
C) UI thread / rendering / animations
High ROI:
- Prefer native-driven transitions (native stack /
react-native-screens).
- Avoid expensive UI operations on animated frames:
- Alpha compositing, heavy shadows, animating image size.
- Use native-driver animations where possible; for complex gestures prefer Reanimated worklets.
See references/03-rendering-js-ui.md.
D) Lists, images, and media
High ROI:
- Fix list fundamentals:
- Stable keys, avoid re-render storms, tune render window.
- Add
getItemLayout when item heights are known.
- If still janky: evaluate FlashList for large/complex feeds.
- Move image-heavy UIs to
expo-image with caching + placeholders.
- For replay-heavy video: use
expo-video caching with a storage policy.
See references/04-lists-images-media.md.
E) Memory leaks / pressure
High ROI:
- Reproduce with a navigation stress loop.
- Take JS heap snapshots (before/after) to spot retained graphs.
- If JS heap stable but RSS grows: switch to native allocation tools.
See references/01-profiling-toolchain.md.
F) Network & background work
High ROI:
- Prevent refetch storms: cache + dedupe + prefetch.
- Use platform-appropriate background scheduling (best effort) for sync.
See references/05-network-background.md.
Phase 4 — Regression control (the “next level”)
Minimum viable regression control:
- Budget file committed (bundle size + a few KPI thresholds).
- CI gate that fails on obvious regressions (bundle/update size growth).
- Production monitoring (crash + perf traces) with symbolication.
See references/06-ci-regression.md.
Common pitfalls (things this skill forbids)
- Benchmarking in dev mode and trusting the results.
- Making 5 optimisations at once, then not knowing which mattered.
- “Fixing” a symptom (e.g. bigger splash delay) instead of root cause (slow JS eval).
- Turning on size flags (bundle compression, aggressive shrinking) without measuring startup and runtime.
Fast checklist
References
Start here:
references/00-principles-and-kpis.md
references/01-profiling-toolchain.md
references/02-startup-bundle-ota.md
references/03-rendering-js-ui.md
references/04-lists-images-media.md
references/06-ci-regression.md
External links: see references/resources.md.
1---
2name: optimising-expo-react-native-performance
3description: Diagnose, improve, and prevent performance regressions in Expo-based React Native apps using release-build profiling, KPI budgets, and targeted fixes across startup, rendering, lists, images, memory, and networking.
4version: 2.0.0
5license: MIT
6tags:
7 - react-native
8 - expo
9 - performance
10 - profiling
11 - optimisation
12 - hermes
13 - metro
14 - flashlist
15 - reanimated
16 - eas
17metadata:
18 source: https://skillmd.com/skills/tristanmanchester/optimising-expo-react-native-performance
19---
20
21## Summary
22
23This skill turns “the app feels slow/janky” into a **measured**, **repeatable**, and **shippable** optimisation program for Expo-managed React Native apps.
24
25Non‑negotiables:
26- Optimise against **user-visible KPIs** (startup/TTI, scroll FPS, navigation responsiveness, memory growth, p95 network latency).
27- Profile in **production-like builds** (release / profile / debugOptimized) — **not** in dev mode.
28- Make **one change at a time**, re-measure, and keep a rollback path.
29
30## When to use
31
32Use when you need to:
33- Fix **slow startup**, “white screen”, or delayed time-to-interactive.
34- Fix **scroll jank**, dropped frames, sluggish taps, or slow transitions.
35- Reduce **memory growth**, crashes under pressure, or image/video bloat.
36- Reduce **OTA update size**, JS bundle size, or Android binary size.
37- Add **regression prevention**: perf budgets + CI gates + production monitoring.
38
39## When NOT to use
40
41Don’t use this skill to:
42- Prematurely micro-optimise already-smooth screens with no KPI regression.
43- Make changes without a reproducible scenario and a baseline.
44- “Optimise” by switching libraries blindly (measure first).
45
46## Inputs
47
48- Repo (Expo managed or CNG/prebuild), ideally with:
49 - `package.json`
50 - `app.json` / `app.config.*`
51 - `metro.config.js` (if present)
52 - `babel.config.*`
53 - `eas.json` (if using EAS)
54- A concrete report of the problem:
55 - Device(s), OS versions, and which flow feels slow.
56 - Steps to reproduce (or a screen name if using Expo Router).
57
58If details are missing, infer as much as possible from the repo and propose a minimal repro script.
59
60## Outputs
61
62Deliver **both**:
631) **Perf audit report** (see template in `assets/templates/perf-audit-report-template.md`):
64 - KPIs + budgets
65 - Baseline measurements (device + build type)
66 - Root cause hypothesis + evidence
67 - Fix plan (ordered by ROI / risk)
68 - Before/after measurements
692) **Code changes** (PR-ready) implementing the top fixes, plus:
70 - Updated perf budgets (if needed)
71 - CI gate(s) for bundle/update size at minimum
72
73## Tooling assumptions
74
75You can use:
76- Expo CLI (`npx expo …`), EAS CLI (`eas …`) where available.
77- React Native DevTools (Performance + Memory panels) for JS-level analysis.
78- Native profilers (Android Studio, Xcode Instruments) for CPU/memory/UI tracing.
79
80You should prefer:
81- **Release/profile builds** for measurement.
82- **Same device class** and **same scenario script** for before/after.
83
84## The optimisation workflow (high level)
85
861) **Define KPIs + budgets** (3–6 metrics max). Pick what users feel.
872) **Create a repeatable scenario** (startup, list scroll, key navigation, etc.).
883) **Measure baseline in a production-like build**.
894) **Classify the bottleneck domain**:
90 - Startup/bundle
91 - JS thread
92 - UI thread
93 - Lists/images
94 - Memory
95 - Network/background
965) Apply **targeted fixes** (smallest change, highest ROI first).
976) **Re-measure**. Keep only changes with KPI wins.
987) Add **regression control** (budgets + CI gates + monitoring).
99
100## Detailed playbook
101
102### Phase 0 — Establish reality (no guesswork)
103
104**0.1 Identify versions and architecture**
105- Expo SDK version, React Native version, React version.
106- New Architecture status (mandatory in newer SDKs).
107- JS engine (Hermes/JSC/V8), OTA updates usage (`expo-updates`).
108- Major perf-sensitive libs: navigation (Expo Router/React Navigation), lists (FlashList), animation (Reanimated), images (`expo-image`).
109
110**0.2 Choose KPIs (pick 3–6)**
111Suggested defaults:
112- Cold start: **time-to-first-render** and/or **time-to-interactive**
113- Scroll: dropped frames / FPS on the heaviest list
114- Navigation: p95 screen transition time for a representative flow
115- Memory: steady-state RSS after repeating a navigation loop 5–10×
116- Network: p95 API latency on a key endpoint
117
118Record budgets as numbers (not “fast”). See `references/00-principles-and-kpis.md`.
119
120**0.3 Choose build type for measuring**
121- Prefer store-equivalent **Release**.
122- If you need debuggability, use Android “profileable” builds, iOS Instruments, or Expo’s `debugOptimized` where applicable.
123
124### Phase 1 — Baseline measurement (release-build discipline)
125
126**1.1 Baseline checklist (must pass)**
127- Dev mode off.
128- No remote JS debugging.
129- Same device, same OS version, same network conditions.
130- Warm vs cold start explicitly noted.
131
132**1.2 Capture traces and numbers**
133- React Native DevTools:
134 - Performance trace (JS execution + React tracks + network events)
135 - Heap snapshot (if memory suspected)
136- Native tools:
137 - Android Studio System Trace for jank attribution
138 - Xcode Instruments (Time Profiler / Allocations / Leaks)
139
140Store raw artefacts (trace files, screenshots) alongside your report.
141
142### Phase 2 — Decide the bottleneck domain
143
144Use this decision rubric:
145- **Startup slow**: long splash, white screen, slow first render → startup/bundle.
146- **Taps lag / transitions slow** but scrolling OK → JS thread or navigation.
147- **Scroll stutters** even with little JS work → UI thread or list/render cost.
148- **Memory climbs over time** → leak / image/video pressure.
149- **Everything waits on API** → network/caching.
150
151### Phase 3 — Apply high-ROI fixes by domain
152
153#### A) Startup & bundle
154Do in this order:
1551) **Stop doing work before first paint**
156 - Gate only critical assets (fonts, tiny config) and hide splash ASAP.
1572) **Confirm Hermes**
158 - Make it explicit in app config if necessary.
159 - If you use OTA updates, ensure runtime compatibility when engine/bytecode changes.
1603) **Shrink JS evaluation**
161 - Prefer ESM imports, avoid breaking tree shaking.
162 - Consider Metro `inlineRequires` (validate side effects!).
1634) **Control OTA payloads**
164 - Configure update asset inclusion/exclusion and verify assets.
1655) **Android size knobs (measure trade-offs)**
166 - Enable R8 minify + resource shrinking.
167 - Treat bundle compression as a measured toggle (smaller APK vs slower startup).
168
169See `references/02-startup-bundle-ota.md`.
170
171#### B) JS thread stalls (renders + computation)
172High ROI:
1731) Remove production `console.*`.
1742) Defer heavy work with `InteractionManager` / `requestAnimationFrame`.
1753) Reduce re-renders:
176 - Stabilise props, split context, memoise hot rows.
177 - Consider **React Compiler** (branch rollout + profiling + easy rollback).
178
179See `references/03-rendering-js-ui.md`.
180
181#### C) UI thread / rendering / animations
182High ROI:
1831) Prefer native-driven transitions (native stack / `react-native-screens`).
1842) Avoid expensive UI operations on animated frames:
185 - Alpha compositing, heavy shadows, animating image size.
1863) Use native-driver animations where possible; for complex gestures prefer Reanimated worklets.
187
188See `references/03-rendering-js-ui.md`.
189
190#### D) Lists, images, and media
191High ROI:
1921) Fix list fundamentals:
193 - Stable keys, avoid re-render storms, tune render window.
194 - Add `getItemLayout` when item heights are known.
1952) If still janky: evaluate FlashList for large/complex feeds.
1963) Move image-heavy UIs to `expo-image` with caching + placeholders.
1974) For replay-heavy video: use `expo-video` caching with a storage policy.
198
199See `references/04-lists-images-media.md`.
200
201#### E) Memory leaks / pressure
202High ROI:
2031) Reproduce with a navigation stress loop.
2042) Take JS heap snapshots (before/after) to spot retained graphs.
2053) If JS heap stable but RSS grows: switch to native allocation tools.
206
207See `references/01-profiling-toolchain.md`.
208
209#### F) Network & background work
210High ROI:
2111) Prevent refetch storms: cache + dedupe + prefetch.
2122) Use platform-appropriate background scheduling (best effort) for sync.
213
214See `references/05-network-background.md`.
215
216### Phase 4 — Regression control (the “next level”)
217
218Minimum viable regression control:
219- **Budget file** committed (bundle size + a few KPI thresholds).
220- **CI gate** that fails on obvious regressions (bundle/update size growth).
221- **Production monitoring** (crash + perf traces) with symbolication.
222
223See `references/06-ci-regression.md`.
224
225## Common pitfalls (things this skill forbids)
226
227- Benchmarking in dev mode and trusting the results.
228- Making 5 optimisations at once, then not knowing which mattered.
229- “Fixing” a symptom (e.g. bigger splash delay) instead of root cause (slow JS eval).
230- Turning on size flags (bundle compression, aggressive shrinking) without measuring startup and runtime.
231
232## Fast checklist
233
234- [ ] KPIs chosen (3–6) + budgets written down
235- [ ] Baseline measured in production-like build
236- [ ] Bottleneck domain identified with evidence
237- [ ] One fix at a time + before/after numbers
238- [ ] At least one regression gate added (bundle/update size)
239- [ ] Monitoring configured (crash + perf)
240
241## References
242
243Start here:
244- `references/00-principles-and-kpis.md`
245- `references/01-profiling-toolchain.md`
246- `references/02-startup-bundle-ota.md`
247- `references/03-rendering-js-ui.md`
248- `references/04-lists-images-media.md`
249- `references/06-ci-regression.md`
250
251External links: see `references/resources.md`.