RN Performance Monitor

Find the frame that missed, and the component that cost it.

A macOS app that measures a React Native app on a real device, simulator or emulator, turns the numbers into ranked findings with a file and a line, and serves all of it over MCP so Claude Code can read the analysis and make the fix.

96 consecutive frame times from a list screen. Eleven percent exceed the 16.7 millisecond budget, with two renders peaking near 60 milliseconds. 16.7ms budget
Frame p50
11.1ms
Frame p95
25.0ms
Worst frame
60ms
Frames over budget
11%

Past 10%, the monitor raises ui-jank and names the component that was re-rendering while those frames were missed.

What it measures

Two halves. The host watches the process from outside over adb, simctl and devicectl; the SDK watches it from inside. They merge into one timeline, so a memory climb from adb sits on the same chart as the component that was re-rendering while it happened.

SourceMetricsNeeds
Android Over adb: CPU including per-thread (JS, native modules, render), PSS and RSS, Java heap, native heap, graphics memory, real per-frame timings with p50/p95/p99 and jank %, logcat nothing in the app
iOS simulator CPU, resident memory, os_log stream nothing in the app
iOS device CPU and physical footprint via devicectl and xctrace Xcode, a paired device
In-app SDK JS FPS, JS event-loop stalls, JS heap on Hermes, bridge traffic, per-component render counts, render cost and wasted renders, time to interactive, screen changes, crashes one import
Native frame module UI-thread FPS, frame intervals p50/p95/p99, jank % against the display's real refresh rate; physical footprint on iOS, Java and native heap on Android a rebuild

You can start with nothing installed in your app. On Android, adb alone gives you CPU, every memory pool and real frame timings. The SDK is what adds attribution — which component, which screen, which file.

Quickstart

From nothing installed to a first recording.

  1. Install the app

    Download the latest release, open the DMG and drag the app to Applications. It is signed and notarised, so it opens on a double-click — nothing to clone, build or unquarantine.

    Measuring Android needs adb on your PATH; iOS needs Xcode's command line tools. Both are checked at startup and named in the device list if they are missing.

  2. Pick a device

    Open the app. Your devices appear in the sidebar — booted simulators, running emulators, anything on adb devices, and paired iPhones. Pick one.

  3. Choose the app under test

    Type into the filter above the picker. A real iPhone lists upwards of 200 apps, three quarters of them com.apple.* services, so the list is split: yours first, platform services grouped underneath. Nothing is preselected unless one of your apps is already running.

  4. Record, exercise, stop

    Press Start recording, drive the screen you care about for at least 30 seconds, then stop. Short recordings mislead — see Limits.

  5. Read the findings

    The Findings tab opens first and ranks what it found, each with the evidence behind it and, where the SDK was reporting, the component and source file to change.

  6. Let an agent fix them

    Run this inside the React Native project you are profiling:

    $ claude mcp add rnperf -- npx -y @rnperf/mcp-server

    Claude can now record, read the findings, open the files they name and make the edits — see Claude Code and MCP.

For findings that name a component and a line, add the SDK to the app under test: npm install @rnperf/sdk. Without it you still get CPU, memory and real frame timings; with it you get attribution — The in-app SDK.

The desktop app

Install a release

Download RN-Performance-Monitor-<version>-arm64.dmg, open it and drag the app to Applications.

Releases are signed with a Developer ID and notarised by Apple, and the ticket is stapled to both the app and the DMG — so a download opens on a double-click, offline included. Each release states in its own notes whether it was signed; a build made without the credentials says so, and needs the quarantine flag cleared. What it takes to produce one is in Handing it to someone else.

If the release was not notarised, macOS refuses it on a machine other than the one that built it: source=Unnotarized Developer ID. Clear the quarantine flag yourself:

$ xattr -dr com.apple.quarantine "/Applications/RN Performance Monitor.app"

Build it yourself

$ npm run build                       # every package
$ npm -w @rnperf/desktop run package   # → apps/desktop/release/*.dmg
$ npm -w @rnperf/desktop run package:dir # unpacked .app, skips the DMG

The main process is bundled with esbuild before packaging, so the daemon and its dependencies end up inside the app and nothing is resolved at runtime. This is not an optimisation: npm workspaces hoist those packages to the repo root as symlinks, and electron-builder cannot follow a symlink into an app bundle.

Signing

Pass the certificate's common name only, with no Developer ID Application: prefix.

$ security find-identity -v -p codesigning   # find yours
$ export CSC_NAME="Your Name (TEAMID)"
$ npm -w @rnperf/desktop run package

The app uses the hardened runtime, with entitlements in apps/desktop/build/entitlements.mac.plist. Electron's JIT needs allow-jit and allow-unsigned-executable-memory; the daemon shells out to adb and xcrun, which needs disable-library-validation.

Handing it to someone else

A Developer ID signature is not enough on its own. Gatekeeper rejects a signed but unnotarised build on any Mac except the one that made it, with source=Unnotarized Developer ID. Notarisation is what removes the step where the recipient has to be talked through a terminal command — it is the difference between double-click it and first, clear the quarantine flag.

You need three things, all from the same Apple Developer account that issued the certificate:

VariableWhere it comes from
APPLE_IDThe Apple ID email on the developer account
APPLE_APP_SPECIFIC_PASSWORDappleid.apple.com → Sign-In and Security → App-Specific Passwords. Not your account password; Apple rejects that
APPLE_TEAM_IDThe ten characters in brackets after your certificate's name
$ export CSC_NAME="Your Name (TEAMID)"
$ export APPLE_ID=you@example.com
$ export APPLE_APP_SPECIFIC_PASSWORD=xxxx-xxxx-xxxx-xxxx
$ export APPLE_TEAM_ID=TEAMID
$ npm -w @rnperf/desktop run package:notarized

package:notarized passes -c.mac.notarize=true, which is exactly what the release workflow passes in CI, so a build cut by hand and a tagged one produce the same artifact. The default package script leaves notarisation off, because turning it on without credentials fails the build rather than quietly skipping.

electron-builder uploads the app, waits for Apple, and staples the ticket to the .app. Stapling is the part that matters for a recipient: it attaches the ticket to the file itself, so the app opens on a machine that is offline or behind a firewall that cannot reach Apple. Expect several minutes of waiting with no output.

electron-builder stops at the app. It notarises the bundle and then builds the DMG around it, so the disk image — the file people actually download — comes out unsigned and unstapled, and stapler validate reports does not have a ticket stapled to it while every other check passes. The afterAllArtifactBuild hook in apps/desktop/build/notarize-dmg.cjs closes that gap: it signs, submits and staples the DMG too, and skips itself when no credentials are set.

Check the DMG before you send it — on the DMG, not just the app inside it:

$ xcrun stapler validate "apps/desktop/release/RN-Performance-Monitor-0.1.0-arm64.dmg"
$ spctl -a -vvv -t install "apps/desktop/release/RN-Performance-Monitor-0.1.0-arm64.dmg"

source=Notarized Developer ID means anyone can open it. source=Unnotarized Developer ID means they cannot, whatever the build log said.

Test it somewhere the quarantine flag is real. A build opens on the machine that produced it whether or not it is notarised, so that machine cannot tell you anything. Download it through a browser on another Mac, or fake the flag: xattr -w com.apple.quarantine "0081;00000000;Safari;" /path/to.dmg.

In CI all of this is handled for you — see Releases and CI. The MCP server and the SDK need none of it: a .mjs file and an npm package are not subject to Gatekeeper.

The in-app SDK

@rnperf/sdk is what turns “this screen is janky” into “this component re-rendered 37 times a second, in src/screens/Checkout.tsx:84”.

Install

$ npm install @rnperf/sdk
$ cd ios && pod install              # picks up the RNPerfSDK native module

To try a change to the SDK before it is released, install the tarball or the path instead:

$ npm pack -w @rnperf/sdk              # → rnperf-sdk-0.1.0.tgz
$ npm install /path/to/rnperf-sdk-0.1.0.tgz

# Or straight from a path, for a repo you control
$ npm install file:/path/to/react-native-performance-monitor/packages/rn-sdk

npm cannot install a subdirectory of a git repository, so a plain git dependency pointing at this monorepo installs the repo root, not the SDK. Use the published package, or the tarball.

Start it

index.js — before registering the root component
import { startPerfMonitor } from '@rnperf/sdk';

startPerfMonitor();   // host is derived from the Metro bundle URL

It is a no-op in release builds unless you pass enableInRelease: true, and the transport fails silently with backoff when no daemon is listening — so leaving the call in costs nothing when you are not profiling.

Profiling a release build

A dev bundle runs hot enough that its numbers are their own story. To measure the build you actually ship, on a device you are holding:

startPerfMonitor({ enableInRelease: true, host: '192.168.1.5' });

host is not optional here. Auto-discovery reads Metro's address out of the bundle URL, and a release bundle is loaded from assets:// or file:// — there is no address in it. Pass your Mac's LAN address; the daemon already listens on every interface.

What carries over unchanged, and what does not:

MetricIn a release build
UI-thread frames, jank, refresh rateIdentical. CADisplayLink and Choreographer are not gated on build type
JS fps, stalls, JS heap, bridge callsWork, and are the numbers worth quoting
Memory footprint, screens, TTI, marks, crashesWork
Component rendersAbsent. Two independent reasons, below
Host-side CPUNeeds a cable and a development- or ad-hoc-signed build

Renders go for two reasons at once: React's commit hook, __REACT_DEVTOOLS_GLOBAL_HOOK__, is not installed in a release bundle, and React ships its production renderer, which records no timings to read even if it were. So every render-storm, expensive-render and large-list-unvirtualised finding disappears — on a typical session that is most of them. Frame and stall findings remain, and they are the ones a user would have felt.

Build it for release, not for the store. This measures a release-configuration build on a device you are holding. A TestFlight or App Store build on someone else's phone cannot reach a daemon on your desk, and rnperf is not a field-monitoring product — there is no backend, sampling or consent flow behind it.

If the host is missing the SDK logs it even in release, where its warnings are otherwise silent — look for [rnperf] in the device log. The session records runtime.dev: false, so a recording made this way is labelled for what it is.

Options

OptionDefaultWhat it does
host'auto'Where the daemon is. Derived from Metro's address; pass an IP when you are not using Metro, and always in a release build
appName—Labels the session in the sidebar
bundleId—Lets the daemon pair SDK data with host-side samples for the same process
appVersion—Recorded with the session, so a diff knows which build it compared
enableInReleasefalseRun outside __DEV__. Requires an explicit host, and loses component renders

Better attribution

import { setScreen, reportTTI, createNavigationTracker } from '@rnperf/sdk';

// React Navigation
<NavigationContainer onStateChange={createNavigationTracker(() => navigationRef.getCurrentRoute()?.name)}>

// or by hand
setScreen('Checkout');
reportTTI('Checkout', Date.now() - startedAt);

UI-thread frames

The SDK ships a native module for both platforms — CADisplayLink on iOS, Choreographer on Android. Autolinking finds it; iOS needs pod install, Android just a rebuild.

Frames are counted natively and drained once per reporting interval, because a bridge event per frame would cause the very jank it is meant to measure. Jank is judged against the display's actual budget — 8.3ms on ProMotion, 11.1ms at 90Hz — never a hardcoded 16.7.

Expo Go cannot load the native module. Use a development build (npx expo prebuild). The JavaScript half of the SDK works in Expo Go either way.

On iOS this is the only way to get UI FPS at all — nothing outside the process can read it. On Android it covers the case adb cannot reach: a device on Wi-Fi, a tester's phone, CI. When a cable is attached, device-side values win, because dumpsys sees the whole render pipeline.

Claude Code and MCP

The point of the analysis is that something can act on it. The MCP server exposes every session, metric and finding to a coding agent.

$ claude mcp add rnperf -- npx -y @rnperf/mcp-server
$ claude mcp list                     # rnperf: ... ✓ Connected

Node 20.11 and nothing else: the daemon and every dependency are bundled into the published package, so the install is one file of about a megabyte and no dependency tree. There is no checkout, and no path to get wrong.

Run it from the React Native project you want profiled — the registration is stored per directory, and the agent's working directory is what findings resolve component names against. Add --scope project to commit it to that repo's .mcp.json and share it with the team; the default keeps it to your machine.

For a client that takes a config file rather than a command:

{
  "mcpServers": {
    "rnperf": { "command": "npx", "args": ["-y", "@rnperf/mcp-server"] }
  }
}

Then ask for what you want:

Profile the checkout screen on the emulator and fix whatever is making it janky.

Claude calls list_devices, then start_session, waits while you drive the app, calls stop_session, reads the findings, opens the files they point at and makes the edits. Ask it to verify and it records a second session and calls diff_sessions.

The server starts its own daemon when the desktop app is not running, so the agent workflow needs nothing else open.

Without npm

The same bundle is attached to every release as rnperf-mcp.mjs, and you can build it from a checkout. Useful on a machine that cannot reach the registry, or to try an unreleased change:

$ npm -w @rnperf/mcp-server run bundle   # → packages/mcp-server/bundle/rnperf-mcp.mjs
$ claude mcp add rnperf -- node /path/to/rnperf-mcp.mjs

No signing, no notarisation, no Gatekeeper: a .mjs file run by Node is not a macOS application. The same goes for the npm packages. The DMG is the only artifact that needs notarising before someone else can open it.

Tools

ToolPurpose
list_devicesEvery device, and what each one can measure
list_apps / launch_appFind and start the app under test
start_session / stop_sessionRecord a window of activity
get_findingsRanked problems with evidence, source files and fixes
get_session_summaryp50, p95, min, max and a per-minute trend for every metric
get_metricsRaw samples, for pinpointing one spike
diff_sessionsBefore and after — did the fix work?
get_logsLogs, crashes, screen changes, TTI marks
locate_componentResolve a component name to a file and line
set_project_rootPoint the daemon at your RN project

Set a real project root. Component lookup ripgreps it. Point it at a home directory and every findings request hangs, which is why /, $HOME and one-level-deep paths are rejected outright.

A release-build session carries fewer findings, and the ones it loses are exactly the ones that name a file and line. Component renders are not recorded outside a dev build, so an agent working from that session gets frames, stalls and memory and has to find the component itself. Profile in dev to locate the cause; re-record in release to confirm the fix on the build you ship.

What it looks for

Each finding carries the evidence that produced it. Where the SDK was reporting, it also carries the component and the file.

FindingFires whenPoints at
js-fps-lowJS FPS p05 below 45the worst screen
js-thread-stallA synchronous block over 100msthe worst screen
ui-jankOver 10% of frames miss the refresh budget—
memory-growthA steady climb: >2MB/min, R² >0.75, >5MB total, over at least 45swhich pool
render-stormA component re-rendering >15×/sthe component and file
large-list-unvirtualisedMany cheap renders of one componentthe component and file
expensive-renderA single render over 8ms on averagethe component and file
high-cpuCPU p95 above 85% of a corethe JS thread, if it is the cause
slow-startupTTI over 2sthe screen
bridge-chatterOver 400 bridge calls/s—

Why memory growth needs a window

Growth is judged by the fit of the trend, not just its slope, so a GC sawtooth is not reported as a leak while a steady climb is. It also needs at least 45 seconds and a rise of at least 5MB: every app allocates while it warms up, and a ten-second window of that produces a textbook straight line, R² of 1, and a confident finding that means nothing. The projection in the evidence never extrapolates further ahead than the recording reaches back.

Terminal

Everything the desktop app does is also a command.

$ node packages/daemon/dist/cli.js devices
$ node packages/daemon/dist/cli.js record emulator-5554 \
      --app com.example.app --seconds 30

Sessions are written as JSONL under ~/.rnperf/sessions/<id>/, so a recording survives the app that made it and can be re-read by the MCP server later.

The daemon's port is 8139, not 8787. It walks 8139–8148 when a port is taken and advertises whichever it bound in ~/.rnperf/daemon.json, which is how the desktop app, the CLI and the MCP server find each other.

Releases and CI

Three workflows in .github/workflows/. Everything they need beyond a checkout is listed below; with no secrets configured at all, they still run and produce an unsigned build.

WorkflowRuns onDoes
ci.ymlpushes and pull requestsTypechecks, builds every package, bundles the MCP server, packs the SDK, and packages an unsigned .app on macOS
release.ymla v* tag, or by handBuilds, signs, notarises, and publishes the DMG, the MCP bundle, the SDK tarball and checksums to a GitHub Release
docs.ymlpushes that touch docs/Publishes this page to GitHub Pages

Cutting a release

$ npm version 0.2.0 --workspaces --include-workspace-root --no-git-tag-version
$ git commit -am "Release 0.2.0"
$ git tag v0.2.0 && git push origin main --tags

The workflow refuses to run if the tag and apps/desktop/package.json disagree — electron-builder names the DMG from the package version, and a mismatch ships an asset whose filename contradicts the release it is attached to.

Secrets

Every one of these is optional. Each missing group degrades one step rather than failing the run.

SecretEffect when absent
MACOS_CERTIFICATE_P12
MACOS_CERTIFICATE_PASSWORD
The DMG is built unsigned, and the release notes say so
APPLE_ID
APPLE_APP_SPECIFIC_PASSWORD
APPLE_TEAM_ID
Signed but not notarised — recipients must clear the quarantine flag
NPM_TOKENThe release still carries the SDK tarball and the MCP bundle, but neither package is published to npm. It must be an npm automation token — any other kind is gated behind two-factor auth and stops on EOTP

The certificate is a base64 of the exported .p12. Export it from Keychain Access (Developer ID Application, with its private key), then:

$ base64 -i certificate.p12 | pbcopy   # paste as MACOS_CERTIFICATE_P12

Notarisation adds several minutes to the job while Apple's service processes the upload, and it will fail the release if the credentials are wrong rather than shipping something Gatekeeper blocks. That is deliberate: a release that quietly cannot be opened is worse than no release.

Limits worth knowing

  • Android frame timings need HWUI profiling, which the daemon turns on for you. The property only applies to processes started afterwards, so restart the app once to get p95 and p99 frame times instead of aggregates.
  • iOS UI-thread frames come from the in-app module, never from the host. Nothing outside the process can read them.
  • gfxinfo jank and in-app jank are not the same measure. Android's gfxinfo counts frames whose total latency exceeded the budget; both native modules count refreshes actually missed. Compare uiFps when crossing sources or platforms.
  • The Android native module needs React Native 0.71+. The JavaScript half works from 0.70.
  • Physical iOS devices are sampled by xctrace in ~10s windows, so host-side CPU and memory lag behind. On real hardware the SDK is the better source, and with the native module it reports physical footprint every second — leaving xctrace needed only for CPU.
  • Simulator memory is host memory. It runs higher than the same build on a device. Use it for trends, not absolute budgets.
  • Render tracking needs a dev build — React only records timings in its profiling build, and a release bundle installs no commit hook for it to report through. Frames, stalls and memory are unaffected.
  • Dev bundles run much hotter than release. Compare like for like, and never quote a dev number as a shipping one. To measure the real thing, see Profiling a release build.
  • A release build cannot find the daemon by itself. There is no Metro URL in an embedded bundle, so host has to be passed explicitly.
  • It profiles devices you hold, not users in the field. Everything reports to a daemon on your machine over the LAN. There is no hosted collector.

How it fits together

┌──────────────┐   ws/http    ┌─────────────────┐   stdio/MCP   ┌─────────────┐
│ Desktop app  │◄────────────►│                 │◄─────────────►│ Claude Code │
│ (Electron)   │              │  rnperf daemon  │               │   / agent   │
└──────────────┘              │                 │               └─────────────┘
                              │  collectors +   │
┌──────────────┐   ws ingest  │  analysis       │     adb       ┌─────────────┐
│ @rnperf/sdk  │─────────────►│                 │◄─────────────►│  devices    │
│ (in the app) │              └─────────────────┘  simctl/ps    │             │
└──────────────┘                                   devicectl    └─────────────┘
PackageContains
packages/protocolShared wire types
packages/daemonCollectors, the session engine, analysis, the HTTP and WS API, the CLI
packages/rn-sdk@rnperf/sdk — the in-app probe, with the iOS and Android native modules
packages/mcp-serverThe MCP bridge for Claude Code
apps/desktopElectron and React

Collectors poll in the background and tick() returns a cache. An inline adb shell call takes anywhere from 500ms to several seconds and would starve the whole sample loop — including the SDK data that needs no device access at all. Each collector also has a deadline per tick as a backstop.