@n4zen/perfkit-hud

Optional in-app HUD for PerfKit.

The HUD renders a floating in-app performance overlay for React Native apps using PerfKit. It can show session summary, network calls, JS stalls, startup metrics, frame/jank samples, top offenders, and export actions.

Installation

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

Usage

Initialize PerfKit first:

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

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

installJSEventLoopStallMonitor()

installNativeCollectors({
  startup: true,
  uiFrames: true,
  pollIntervalMs: 1000,
}).catch(() => {})

Mount the HUD near the root of your app:

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

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

Props

type PerfHUDProps = {
  defaultVisible?: boolean
  visible?: boolean
  onVisibleChange?: (visible: boolean) => void
  showPill?: boolean
  intervalMs?: number
}

Example:

<PerfHUD defaultVisible={false} showPill intervalMs={1000} />

What It Shows

• Session duration
• Span/event/sample counts
• JS stall metrics
• Startup metrics
• Android frame metrics
• Recent network requests
• Top network offenders
• Top screen offenders
• Export actions

Expo and Bare React Native

The HUD is designed to be optional and does not require Expo. Clipboard support is best-effort depending on available native modules.

React Native Compatibility

Use the HUD version that matches your PerfKit React Native package:

| PerfKit Version | React Native Support | | --------------- | -------------------- | | 1.x | RN ≤ 0.69 | | 2.x | RN ≥ 0.70 |

Notes

• The HUD is intended for development, profiling, demos, and internal validation.
• For final performance claims, collect metrics from release builds on real devices.
• For full setup, see @n4zen/perfkit-react-native.

License

MIT