Org Skills

react-native-performance

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.

Download .zip Raw Source
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.

npx skills add AGCO-Global/org-skills --skill react-native-performance
# user-level instead of project-level:
npx skills add AGCO-Global/org-skills --skill react-native-performance -g

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.

Skill contents

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 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.

References

Deeper material the agent loads only when needed.