Pulse — Mobile Performance Observability for React Native

Pulse is a production-grade performance observability layer for React Native, built as a TurboModule-powered SDK (PerfKit) with a real-time visual interface for analyzing application behavior under real-world conditions.

---

📚 Table of Contents

• Demo & Visuals
• Executive Summary
• Why This Exists
• Architecture & System Design
• Technical Deep Dive
• Performance & Metrics
• Real-World Validation (Fintech Case Study)
• Developer Experience & Setup
• Design Decisions & Tradeoffs
• Positioning & Differentiation

---

🧪 Demo & Visuals

📱 Dashboard UI

---

🎬 Demo Video

See Pulse in action — a real-time performance observability app powered by PerfKit, showcasing metrics, traces, and runtime insights directly on-device.

---

📊 Pulse App Demo Live walkthrough of Pulse capturing performance data, visualizing metrics, and surfacing bottlenecks in a React Native app. Highlights Real-time performance metrics (TTFF, TTI, jank) Network request tracking + timings Navigation + screen render traces On-device HUD + session insights

---

⬆️ Back to top

---

---

Executive Summary

Modern mobile applications suffer from invisible performance degradation — slow startup times, UI jank, network bottlenecks — that are difficult to detect without specialized tooling.

Pulse solves this by providing:

• Real-time performance telemetry
• Structured session exports
• Visual debugging interface
• Production-compatible instrumentation

The system enables developers to:

• Identify latency bottlenecks (startup, network, rendering)
• Detect UI instability (frame drops, jank)
• Measure JS thread performance (stall detection)
• Analyze real user sessions rather than synthetic benchmarks

Impact:

• Reduced debugging time for performance issues
• Data-driven optimization decisions
• Production-safe observability layer

---

Why This Exists

Most React Native performance tools are:

• Fragmented (FPS tools, network logs, profiler)
• Dev-only (not usable in production builds)
• Hard to correlate (no unified timeline)

Pulse was engineered as a unified system:

Input → Instrumentation → Aggregation → Visualization → Insight

It acts as both:

• A developer SDK (PerfKit)
• A visual observability interface (Pulse app + viewer)

---

Architecture & System Design

High-Level Flow

React Native App
      ↓
@n4zen/perfkit-react-native (TurboModule Layer)
      ↓
@n4zen/perfkit-core (Event Engine)
      ↓
Event Collection (JS + Native)
      ↓
Session Aggregation Engine
      ↓
JSON Export / HUD Overlay (@n4zen/perfkit-hud)
      ↓
Pulse Viewer UI

---

Features

• JS instrumentation (fetch, navigation, screen spans, JS stalls)
• Native collectors (startup + UI frame/jank)
• Safe-by-default privacy/redaction
• HUD overlay for in-app inspection
• Viewer with waterfall timeline, offenders, budgets, and HTML report export

---

Data Pipeline

1. Instrumentation Layer

   • Native (Android/iOS)
   • JS thread hooks
   • Network interceptors (Apisauce)

2. Event Types Captured

   • Startup timings
   • UI frame metrics
   • JS stalls
   • Network spans

3. Aggregation Engine

   • Percentiles (p50, p90, p95)
   • Top offenders
   • Timeline reconstruction

4. Output

   • Structured JSON session
   • Visual dashboard rendering

---

Architecture Diagram

---

Technical Deep Dive

📦 Published Packages (npm)

PerfKit is now available as modular packages on npm:

Package	Description
@n4zen/perfkit-core	Core event engine, aggregation, exports
@n4zen/perfkit-react-native	React Native SDK (TurboModule + JS instrumentation)
@n4zen/perfkit-hud	In-app HUD overlay for real-time inspection

---

Core Stack

Mobile / SDK

• React Native - Expo / Bare RN
• TurboModules (native bridge optimization)
• TypeScript
• Apisauce (network interception)

Build System

• pnpm workspaces
• tsup (bundling)
• Modular package architecture

---

Compatibility Strategy

PerfKit Version	React Native Support
@n4zen/perfkit-react-native@1.x	RN ≤ 0.69
@n4zen/perfkit-react-native@2.x	RN ≥ 0.70

Dual-version strategy ensures compatibility across fragmented RN ecosystems without forced migrations.

---

Instrumentation Logic

Startup Tracking

• Native timestamps (appOnCreate)
• RN content render (rnContent)
• Measures Time to Interactive (TTI)

UI Performance

• Frame duration tracking

• Jank thresholds:

  • 16ms (60fps drop)

  • 33ms (visible lag)

  • 50ms (major lag)

JS Stall Detection

• Interval-based monitoring
• Detects main thread blocking

Network Tracking

• Automatic span creation via interceptor
• Captures duration, route, status, metadata

---

Performance & Metrics

Key Metrics Captured

• Startup latency
• Frame consistency (p50/p90/p95)
• Jank frequency
• JS stall duration
• Network latency distribution

---

🔬 Real-World Validation (Fintech Case Study)

Validated in a production-grade fintech mobile application, without altering business logic.

Key Findings

• Network bottlenecks dominate perceived performance
• JS stalls correlate with heavy UI rendering
• Observable improvements after optimization work

---

🎯 Objective

Evaluate whether PerfKit (via Pulse) can:

• Accurately capture real-world performance signals
• Identify actionable bottlenecks
• Provide measurable improvements across app versions

---

Observations

• Identified slow endpoints (>2s)
• Detected JS thread blocking spikes (>500ms)
• Highlighted UI jank clusters during heavy network activity

---

🔍 Example Session Insights

From an actual captured session:

• Multiple concurrent API calls between 700ms – 1000ms
• One critical endpoint (/activities) peaking at ~2179ms
• JS thread stall spikes up to ~576ms
• Frame drops correlated with network bursts

These were identified directly via PerfKit session export:

---

🧠 Key Findings

1. Network Bottlenecks Dominate Perceived Performance

• Long-tail API calls (>2s) directly impact UI responsiveness
• Parallel requests amplify JS thread pressure

2. JS Stalls Correlate with Heavy Screens

• Large data parsing + rendering → measurable stalls
• Observable via stall tracking (previously invisible)

3. Optimizations Matter

• improvements + internal changes reduced:

  • Startup time
  • Frame instability
  • Network overhead impact

---

📄 Full Case Study

For deeper analysis (methodology, raw logs, extended charts):

👉 View Full Case Study

---

🧩 Why This is Useful

This is not a synthetic benchmark.

This is:

• Real user flows
• Real API latency
• Real UI behavior

---

🛠 Developer Experience & Setup

📦 Installation

npm install @n4zen/perfkit-react-native

---

🚀 Quick Start

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

installPerfKit()

---

📥 Releases & Downloads

📱 Pulse (Demo App)

Use Pulse to explore real performance sessions and visualizations.

• Pulse v1.0.x — PerfKit Demo App
• Includes:
  • Full PerfKit integration
  • Real session playback
  • HUD + viewer interface

👉 Download APK:
https://github.com/n4zen-dev-studio/pulse/releases?q=pulse-v1

---

⚙️ PerfKit SDK

v2.x (Modern React Native)

⚙️ Compatibility

• React Native ≥ 0.70
• Tested with bare React Native
• Tested with Expo

📦 Install

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

• PerfKit v2.0.x — React Native ≥ 0.70
• TurboModules + new architecture support

👉 View Releases:
https://github.com/n4zen-dev-studio/pulse/releases?q=perfkit-v2

---

v1.x (Legacy React Native)

• PerfKit v1.0.x — React Native ≤ 0.69
• Legacy bridge compatibility

⚙️ Compatibility

• React Native ≤ 0.69
• Tested with bare React Native
• Tested with Expo

📦 Install

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

👉 View Releases:
https://github.com/n4zen-dev-studio/pulse/releases?q=perfkit-v1

---

Full Setup

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

Perf.init({
  enabled: true,
  app: { name: "demo" },
  sampling: { spanSampleRate: 1, eventSampleRate: 1, sampleSampleRate: 1 },
})

installPerfKitReactNative({
  enableFetch: true,
  enableJSStalls: true,
})

installNativeCollectors({
  startup: true,
  uiFrames: true,
  pollIntervalMs: 1000,
})

---

📊 Export Session Data

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

const session = await Perf.exportSession()

---

🧩 Optional Integrations

Apisauce Tracking

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

installApisauceTracker(apiInstance)

---

📱 Expo Support

• Works with Expo Dev Client
• Compatible with bare React Native
• No Expo dependency required

---

⚡ Performance Overhead

• Lightweight
• Non-blocking
• Safe for production builds

---

Design Decisions & Tradeoffs

Why TurboModules?

• Reduced bridge overhead
• Lower latency for high-frequency events

Why JSON Export?

• Portable
• Replayable
• Decouples SDK from UI

Why Modular Packages?

• Clear separation of concerns
• Smaller bundle sizes
• Flexible adoption

---

Positioning & Differentiation

Pulse is not just a performance tool.

It is:

• A system-level observability layer
• A visual debugging interface
• A production-safe telemetry pipeline

---

Compared to Alternatives

Feature	Pulse	Traditional Tools
Production Ready	✅	❌
Unified Timeline	✅	❌
JS + Native + Network	✅	❌
Visual Dashboard	✅	❌

---

↑ Back to Top

---

📄 License

MIT License — feel free to use

---

🔗 npm Packages

• https://www.npmjs.com/package/@n4zen/perfkit-core
• https://www.npmjs.com/package/@n4zen/perfkit-react-native
• https://www.npmjs.com/package/@n4zen/perfkit-hud