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.
| Source | Metrics | Needs |
|---|---|---|
| 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.
-
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
adbon yourPATH; iOS needs Xcode's command line tools. Both are checked at startup and named in the device list if they are missing. -
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. -
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. -
Record, exercise, stop
Press Start recording, drive the screen you care about for at least 30 seconds, then stop. Short recordings mislead — see Limits.
-
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.
-
Let an agent fix them
Run this inside the React Native project you are profiling:
$ claude mcp add rnperf -- npx -y @rnperf/mcp-serverClaude 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:
| Variable | Where it comes from |
|---|---|
APPLE_ID | The Apple ID email on the developer account |
APPLE_APP_SPECIFIC_PASSWORD | appleid.apple.com → Sign-In and Security → App-Specific Passwords. Not your account password; Apple rejects that |
APPLE_TEAM_ID | The 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
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:
| Metric | In a release build |
|---|---|
| UI-thread frames, jank, refresh rate | Identical. CADisplayLink and Choreographer are not gated on build type |
| JS fps, stalls, JS heap, bridge calls | Work, and are the numbers worth quoting |
| Memory footprint, screens, TTI, marks, crashes | Work |
| Component renders | Absent. Two independent reasons, below |
| Host-side CPU | Needs 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
| Option | Default | What 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 |
enableInRelease | false | Run 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
| Tool | Purpose |
|---|---|
list_devices | Every device, and what each one can measure |
list_apps / launch_app | Find and start the app under test |
start_session / stop_session | Record a window of activity |
get_findings | Ranked problems with evidence, source files and fixes |
get_session_summary | p50, p95, min, max and a per-minute trend for every metric |
get_metrics | Raw samples, for pinpointing one spike |
diff_sessions | Before and after — did the fix work? |
get_logs | Logs, crashes, screen changes, TTI marks |
locate_component | Resolve a component name to a file and line |
set_project_root | Point 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.
| Finding | Fires when | Points at |
|---|---|---|
js-fps-low | JS FPS p05 below 45 | the worst screen |
js-thread-stall | A synchronous block over 100ms | the worst screen |
ui-jank | Over 10% of frames miss the refresh budget | — |
memory-growth | A steady climb: >2MB/min, R² >0.75, >5MB total, over at least 45s | which pool |
render-storm | A component re-rendering >15×/s | the component and file |
large-list-unvirtualised | Many cheap renders of one component | the component and file |
expensive-render | A single render over 8ms on average | the component and file |
high-cpu | CPU p95 above 85% of a core | the JS thread, if it is the cause |
slow-startup | TTI over 2s | the screen |
bridge-chatter | Over 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.
| Workflow | Runs on | Does |
|---|---|---|
ci.yml | pushes and pull requests | Typechecks, builds every package, bundles the MCP server, packs the SDK, and packages an unsigned .app on macOS |
release.yml | a v* tag, or by hand | Builds, signs, notarises, and publishes the DMG, the MCP bundle, the SDK tarball and checksums to a GitHub Release |
docs.yml | pushes 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.
| Secret | Effect when absent |
|---|---|
MACOS_CERTIFICATE_P12MACOS_CERTIFICATE_PASSWORD | The DMG is built unsigned, and the release notes say so |
APPLE_IDAPPLE_APP_SPECIFIC_PASSWORDAPPLE_TEAM_ID | Signed but not notarised — recipients must clear the quarantine flag |
NPM_TOKEN | The 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.
-
gfxinfojank and in-app jank are not the same measure. Android'sgfxinfocounts frames whose total latency exceeded the budget; both native modules count refreshes actually missed. CompareuiFpswhen 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
xctracein ~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 — leavingxctraceneeded 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
hosthas 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 └─────────────┘
| Package | Contains |
|---|---|
packages/protocol | Shared wire types |
packages/daemon | Collectors, 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-server | The MCP bridge for Claude Code |
apps/desktop | Electron 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.