@n4zen/perfkit-react-native

React Native performance instrumentation for real apps.

PerfKit records app-level performance signals such as startup timing, API latency, JS stalls, screen/navigation spans, and Android frame metrics, then exports a structured JSON session that can be viewed in the PerfKit web viewer or inspected in-app with the HUD.

Built for React Native apps that need lightweight, developer-friendly performance visibility without setting up a full observability backend.

Features

• React Native integration layer for PerfKit
• Fetch tracking
• Axios tracking
• Apisauce tracking
• JS event-loop stall monitoring
• Screen timing hooks
• React Navigation tracing helpers
• Android native startup metrics
• Android UI frame/jank samples
• Session JSON export
• Optional in-app HUD via @n4zen/perfkit-hud
• Works in bare React Native and Expo/Expo Dev Client setups

Packages

| Package | Purpose | |---|---| | @n4zen/perfkit-core | Core session, spans, samples, aggregates, budgets, export engine | | @n4zen/perfkit-react-native | React Native instrumentation layer | | @n4zen/perfkit-hud | Optional in-app performance HUD |

React Native Compatibility

| PerfKit Version | React Native Support | |---|---| | @n4zen/[email protected] | RN ≤ 0.69 | | @n4zen/[email protected] | RN ≥ 0.70 |

This dual-version strategy helps support fragmented React Native ecosystems without forcing teams to migrate before collecting useful metrics.

Both version lines have been tested with real React Native apps, including bare React Native and Expo-based development setups.

Installation

Install the core and React Native package:

npm install @n4zen/perfkit-core @n4zen/perfkit-react-native

Optional HUD:

npm install @n4zen/perfkit-hud

Quick Start

Initialize PerfKit as early as possible in your app startup code:

import { Perf } from "@n4zen/perfkit-core"
import {
  installFetchTracker,
  installJSEventLoopStallMonitor,
  installNativeCollectors,
} from "@n4zen/perfkit-react-native"

Perf.init({
  enabled: true,
  app: {
    name: "My React Native App",
  },
})

installFetchTracker()
installJSEventLoopStallMonitor()

installNativeCollectors({
  startup: true,
  uiFrames: true,
  pollIntervalMs: 1000,
}).catch(() => {
  // Native collectors are optional.
})

Apisauce Tracking

If your app uses Apisauce, attach PerfKit to the Apisauce instance after it is created:

import { create } from "apisauce"
import { installApisauceTracker } from "@n4zen/perfkit-react-native"

const api = create({
  baseURL: "https://api.example.com",
  timeout: 10000,
})

const cleanup = installApisauceTracker(api)

This records spans like:

net.GET /mobile/dashboard
net.POST /login
net.GET /accounts

Axios Tracking

import axios from "axios"
import { installAxiosTracker } from "@n4zen/perfkit-react-native"

const client = axios.create({
  baseURL: "https://api.example.com",
})

const cleanup = installAxiosTracker(client)

Fetch Tracking

import { installFetchTracker } from "@n4zen/perfkit-react-native"

installFetchTracker({
  ignoreUrls: [/localhost:8081/, /10\.0\.2\.2:8081/, /symbolicate/],
})

PerfKit normalizes network routes by default so query-heavy URLs are grouped cleanly.

Example:

/profile?page=1&min_date=...

becomes:

/profile

Raw URL details are still preserved in span attributes for debugging.

JS Stall Monitoring

import { installJSEventLoopStallMonitor } from "@n4zen/perfkit-react-native"

installJSEventLoopStallMonitor({
  intervalMs: 50,
  stallThresholdMs: 100,
})

This records samples such as:

js.stall.ms

Android Native Collectors

import { installNativeCollectors } from "@n4zen/perfkit-react-native"

const cleanupNative = await installNativeCollectors({
  startup: true,
  uiFrames: true,
  pollIntervalMs: 1000,
})

Native Android metrics include:

startup.appOnCreate.ms
startup.activityResume.ms
startup.ttff.ms
startup.rnContent.ms
ui.frame.p50.ms
ui.frame.p90.ms
ui.frame.p95.ms
ui.frame.max.ms
ui.jank.over33.count
ui.jank.over50.count
ui.jank.over100.count

Native collectors are optional. The SDK still works in JS-only mode.

Screen Timing

import { useScreenPerf } from "@n4zen/perfkit-react-native"

function DashboardScreen() {
  const { markInteractive } = useScreenPerf("Dashboard")

  // Call when the screen is ready for user interaction.
  markInteractive()

  return null
}

React Navigation Tracing

import { installNavigationTracing } from "@n4zen/perfkit-react-native"

const cleanupNav = installNavigationTracing({
  navigationRef,
})

Exporting a Session

import { Perf } from "@n4zen/perfkit-core"

const session = Perf.exportSession()
console.log(JSON.stringify(session, null, 2))

Example output includes:

{
  "schemaVersion": "1.0",
  "session": {
    "id": "s_...",
    "durationMs": 11699
  },
  "timeline": [],
  "aggregates": {},
  "topOffenders": {},
  "budgets": {
    "results": []
  }
}

Optional In-App HUD

Install:

npm install @n4zen/perfkit-hud

Mount near the root of your app:

import { PerfHUD } from "@n4zen/perfkit-hud"

export function AppRoot() {
  return (
    <>
      <AppNavigator />
      <PerfHUD />
    </>
  )
}

The HUD shows recent network calls, JS stalls, startup metrics, frame samples, top offenders, and export actions.

Recommended Release Testing

Debug builds are useful for proving instrumentation works, but performance numbers should be collected from release builds.

Recommended comparison setup:

• same physical Android device
• same build type
• same network
• same account/data state
• same flow order
• export JSON from each run
• compare in the PerfKit viewer

What PerfKit Is Good For

PerfKit is designed for:

• React Native performance comparisons
• before/after performance validation
• API latency visibility
• JS stall detection
• startup timing checks
• lightweight performance diagnostics
• portfolio/demo performance reports
• local-first performance analysis without a backend

Notes

• Native Android collectors are optional.
• iOS native collector support may depend on the app deployment target and setup.
• HUD is optional and does not require Expo.
• Expo and bare React Native apps are both supported.
• For older React Native apps, use the 1.x line.
• For newer React Native apps, use the 2.x line.

License

MIT