optimising-expo-react-native-performance

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:

1. 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
2. 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)

1. Define KPIs + budgets (3–6 metrics max). Pick what users feel.
2. Create a repeatable scenario (startup, list scroll, key navigation, etc.).
3. Measure baseline in a production-like build.
4. Classify the bottleneck domain:
   • Startup/bundle
   • JS thread
   • UI thread
   • Lists/images
   • Memory
   • Network/background
5. Apply targeted fixes (smallest change, highest ROI first).
6. Re-measure. Keep only changes with KPI wins.
7. 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:

1. Stop doing work before first paint
   • Gate only critical assets (fonts, tiny config) and hide splash ASAP.
2. Confirm Hermes
   • Make it explicit in app config if necessary.
   • If you use OTA updates, ensure runtime compatibility when engine/bytecode changes.
3. Shrink JS evaluation
   • Prefer ESM imports, avoid breaking tree shaking.
   • Consider Metro inlineRequires (validate side effects!).
4. Control OTA payloads
   • Configure update asset inclusion/exclusion and verify assets.
5. 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:

1. Remove production console.*.
2. Defer heavy work with InteractionManager / requestAnimationFrame.
3. 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:

1. Prefer native-driven transitions (native stack / react-native-screens).
2. Avoid expensive UI operations on animated frames:
   • Alpha compositing, heavy shadows, animating image size.
3. 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:

1. Fix list fundamentals:
   • Stable keys, avoid re-render storms, tune render window.
   • Add getItemLayout when item heights are known.
2. If still janky: evaluate FlashList for large/complex feeds.
3. Move image-heavy UIs to expo-image with caching + placeholders.
4. 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:

1. Reproduce with a navigation stress loop.
2. Take JS heap snapshots (before/after) to spot retained graphs.
3. If JS heap stable but RSS grows: switch to native allocation tools.

See references/01-profiling-toolchain.md.

F) Network & background work

High ROI:

1. Prevent refetch storms: cache + dedupe + prefetch.
2. 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

• KPIs chosen (3–6) + budgets written down
• Baseline measured in production-like build
• Bottleneck domain identified with evidence
• One fix at a time + before/after numbers
• At least one regression gate added (bundle/update size)
• Monitoring configured (crash + perf)

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.