@grafana/faro-react-native 1.0.0-alpha.1

package/ios/RefreshRateVitals.swift

@@ -0,0 +1,220 @@
+import Foundation
+import UIKit
+
+/// Provides frame rate and refresh rate monitoring using CADisplayLink.
+///
+/// Implementation ported from Faro Flutter SDK:
+/// https://github.com/grafana/faro-flutter-sdk/blob/main/ios/Classes/RefreshRateVitals.swift
+///
+/// Uses CADisplayLink to measure actual frame durations and calculate FPS.
+/// Handles ProMotion displays (120Hz) by normalizing to 60 FPS baseline.
+@objc public class RefreshRateVitals: NSObject {
+    private var displayLink: CADisplayLink?
+    private var lastFrameTimestamp: CFTimeInterval?
+    private var nextFrameDuration: CFTimeInterval?
+    
+    /// Normalized refresh rate for backend compatibility (default 60 FPS)
+    private var normalizedRefreshRate: Double = 60.0
+    
+    /// Target FPS for slow frame detection
+    private var targetFps: Double = 60.0
+    
+    /// Threshold in seconds for frozen frame detection
+    private var frozenFrameThreshold: Double = 0.100
+    
+    /// Last calculated refresh rate
+    @objc public private(set) var lastRefreshRate: Double = 0.0
+    
+    /// Count of slow frame events since last reset (not individual frames)
+    @objc public private(set) var slowFrameEventCount: Int = 0
+    
+    /// Count of frozen frames since last reset
+    @objc public private(set) var frozenFrameCount: Int = 0
+    
+    /// Total duration of frozen frames in milliseconds
+    @objc public private(set) var frozenFrameDurationMs: Double = 0
+    
+    /// Whether monitoring is active
+    @objc public private(set) var isMonitoring: Bool = false
+    
+    /// Shared instance for global access
+    @objc public static let shared = RefreshRateVitals()
+    
+    // MARK: - Slow Frame Event Detection
+    
+    /// Whether we're currently in a slow frame event
+    private var inSlowFrameEvent: Bool = false
+    
+    /// Timestamp when current slow frame event started
+    private var slowFrameEventStartTime: CFTimeInterval = 0
+    
+    /// Minimum duration (in seconds) for a slow frame event to be counted (prevents noise)
+    private let slowFrameEventMinDuration: Double = 0.050  // ~3 frames at 60fps
+    
+    private override init() {
+        super.init()
+    }
+    
+    // MARK: - Public Methods
+    
+    /// Configure monitoring parameters
+    /// - Parameters:
+    ///   - targetFps: Target FPS for slow frame detection (default 60)
+    ///   - frozenFrameThresholdMs: Threshold in ms for frozen frames (default 100)
+    ///   - normalizedRefreshRate: Normalized rate for ProMotion displays (default 60)
+    @objc public func configure(
+        targetFps: Double,
+        frozenFrameThresholdMs: Double,
+        normalizedRefreshRate: Double
+    ) {
+        self.targetFps = targetFps
+        self.frozenFrameThreshold = frozenFrameThresholdMs / 1000.0
+        self.normalizedRefreshRate = normalizedRefreshRate
+    }
+    
+    /// Start frame monitoring
+    @objc public func start() {
+        guard !isMonitoring else { return }
+        
+        displayLink = CADisplayLink(target: self, selector: #selector(displayTick(link:)))
+        displayLink?.add(to: .main, forMode: .common)
+        isMonitoring = true
+        
+        // Reset counters
+        slowFrameEventCount = 0
+        frozenFrameCount = 0
+        frozenFrameDurationMs = 0
+        lastFrameTimestamp = nil
+        nextFrameDuration = nil
+        inSlowFrameEvent = false
+        slowFrameEventStartTime = 0
+    }
+    
+    /// Stop frame monitoring
+    @objc public func stop() {
+        displayLink?.invalidate()
+        displayLink = nil
+        lastFrameTimestamp = nil
+        nextFrameDuration = nil
+        isMonitoring = false
+    }
+    
+    /// Get current refresh rate
+    @objc public func getRefreshRate() -> Double {
+        return lastRefreshRate
+    }
+    
+    /// Get and reset slow frame event count
+    @objc public func getAndResetSlowFrames() -> Int {
+        let count = slowFrameEventCount
+        slowFrameEventCount = 0
+        return count
+    }
+    
+    /// Get and reset frozen frame count
+    @objc public func getAndResetFrozenFrames() -> Int {
+        let count = frozenFrameCount
+        frozenFrameCount = 0
+        return count
+    }
+    
+    /// Get and reset frozen frame duration in milliseconds
+    @objc public func getAndResetFrozenDuration() -> Double {
+        let duration = frozenFrameDurationMs
+        frozenFrameDurationMs = 0
+        return duration
+    }
+    
+    // MARK: - Private Methods
+    
+    @objc private func displayTick(link: CADisplayLink) {
+        // Check for frozen frames FIRST (before calculateFPS updates lastFrameTimestamp)
+        if let lastTimestamp = lastFrameTimestamp {
+            let frameDuration = link.timestamp - lastTimestamp
+            if frameDuration > frozenFrameThreshold {
+                frozenFrameCount += 1
+                
+                // Track duration in milliseconds
+                let durationMs = frameDuration * 1000
+                frozenFrameDurationMs += durationMs
+                
+                NSLog("[Faro] Frozen frame detected! Duration: %.0fms (threshold: %.0fms)", durationMs, frozenFrameThreshold * 1000)
+            }
+        }
+        
+        guard let fps = calculateFPS(provider: link) else { return }
+        
+        lastRefreshRate = fps
+        
+        // Check for slow frames using event-based detection
+        // A slow frame "event" is a period of consecutive frames below target FPS
+        // This groups consecutive slow frames to report meaningful jank, not microsecond variations
+        let isSlow = fps < targetFps
+        
+        // 🔍 TEMP DEBUG LOG - Remove after analysis
+        if isSlow {
+            NSLog("[Faro DEBUG IOS] 🐌 Slow frame detected: %.1f FPS (target: %.1f)", fps, targetFps)
+        }
+        
+        if isSlow {
+            if !inSlowFrameEvent {
+                // Start new slow frame event
+                inSlowFrameEvent = true
+                slowFrameEventStartTime = link.timestamp
+            }
+        } else {
+            // Frame is good - check if we should end the current slow frame event
+            if inSlowFrameEvent {
+                let eventDuration = link.timestamp - slowFrameEventStartTime
+                let eventDurationMs = eventDuration * 1000
+                
+                // Only count as a slow frame event if it lasted long enough to be user-perceptible
+                // This filters out single-frame dips that don't affect user experience
+                if eventDuration >= slowFrameEventMinDuration {
+                    slowFrameEventCount += 1
+                    // 🔍 TEMP DEBUG LOG - Remove after analysis
+                    NSLog("[Faro DEBUG IOS] ✅ COUNTED as event (%.0fms)! Total events now: %d", eventDurationMs, slowFrameEventCount)
+                } else {
+                    // 🔍 TEMP DEBUG LOG - Remove after analysis
+                    NSLog("[Faro DEBUG IOS] ❌ NOT counted (%.0fms is too short). Total events still: %d", eventDurationMs, slowFrameEventCount)
+                }
+                
+                inSlowFrameEvent = false
+                slowFrameEventStartTime = 0
+            }
+        }
+    }
+    
+    /// Calculate frames per second from display link timing
+    private func calculateFPS(provider: CADisplayLink) -> Double? {
+        guard let lastTimestamp = lastFrameTimestamp else {
+            // First frame - just record timestamp
+            lastFrameTimestamp = provider.timestamp
+            nextFrameDuration = provider.targetTimestamp - provider.timestamp
+            return nil
+        }
+        
+        let currentFrameDuration = provider.timestamp - lastTimestamp
+        guard currentFrameDuration > 0 else { return nil }
+        
+        let currentFPS = 1.0 / currentFrameDuration
+        var fps: Double
+        
+        // ProMotion displays can have refresh rates higher than 60 FPS
+        // Normalize to backend-supported rate for consistent metrics
+        if let expectedFrameDuration = nextFrameDuration,
+           expectedFrameDuration > 0,
+           UIScreen.main.maximumFramesPerSecond > 60 {
+            let expectedFPS = 1.0 / expectedFrameDuration
+            fps = currentFPS * (normalizedRefreshRate / expectedFPS)
+        } else {
+            fps = currentFPS
+        }
+        
+        // Update timestamps for next frame
+        lastFrameTimestamp = provider.timestamp
+        nextFrameDuration = provider.targetTimestamp - provider.timestamp
+        
+        return fps
+    }
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@grafana/faro-react-native",
+  "version": "1.0.0-alpha.1",
+  "description": "Faro instrumentations, metas, transports for React Native.",
+  "keywords": [
+    "observability",
+    "apm",
+    "rum",
+    "logs",
+    "traces",
+    "metrics",
+    "react-native",
+    "mobile"
+  ],
+  "license": "Apache-2.0",
+  "author": "Grafana Labs",
+  "homepage": "https://github.com/grafana/faro-react-native-sdk",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/grafana/faro-react-native-sdk.git",
+    "directory": "packages/react-native"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "react-native": "./src/index.ts",
+  "files": [
+    "dist",
+    "src",
+    "ios",
+    "android",
+    "FaroReactNative.podspec",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "yarn watch",
+    "build": "run-s 'build:*'",
+    "build:compile": "run-p 'build:compile:*'",
+    "build:compile:cjs": "tsc --build tsconfig.cjs.json",
+    "build:compile:esm": "tsc --build tsconfig.esm.json",
+    "watch": "run-p 'watch:compile:*'",
+    "watch:compile:cjs": "yarn build:compile:cjs -w",
+    "watch:compile:esm": "yarn build:compile:esm -w",
+    "clean": "rimraf dist/ yarn-error.log",
+    "quality": "run-s 'quality:*'",
+    "quality:test": "../../node_modules/.bin/jest",
+    "quality:format": "prettier --cache --cache-location=../../.cache/prettier/reactNative --ignore-path ../../.prettierignore -w \"./**/*.{js,jsx,ts,tsx,css,scss,md,yaml,yml,json}\"",
+    "quality:lint": "run-p 'quality:lint:eslint' 'quality:lint:prettier'",
+    "quality:lint:eslint": "eslint --cache --cache-location ../../.cache/eslint/reactNative \"./**/*.{js,jsx,ts,tsx}\"",
+    "quality:lint:prettier": "prettier --cache --cache-location=../../.cache/prettier/reactNative --ignore-path ../../.prettierignore -c \"./**/*.{js,jsx,ts,tsx,css,scss,md,yaml,yml,json}\"",
+    "quality:circular-deps": "madge --circular ."
+  },
+  "dependencies": {
+    "@grafana/faro-core": "^2.2.3",
+    "@react-native-async-storage/async-storage": "^1.21.0",
+    "react-native-device-info": "^11.1.0"
+  },
+  "peerDependencies": {
+    "@grafana/faro-react-native-tracing": ">=1.0.0",
+    "@react-navigation/native": ">=6.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.70.0"
+  },
+  "peerDependenciesMeta": {
+    "@grafana/faro-react-native-tracing": {
+      "optional": true
+    },
+    "@react-navigation/native": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "24.10.1",
+    "@types/react": "^19.1.1",
+    "@types/react-native": "^0.73.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "486ee5d65eb1e274a7e207e0c9c04cccffe98c2e"
+}

package/src/config/getRNInstrumentations.test.ts

@@ -0,0 +1,116 @@
+/** Keeps tests working without a workspace devDependency (avoids npm/Lerna cycle: tracing → react-native → tracing). */
+jest.mock('@grafana/faro-react-native-tracing', () => {
+  const { BaseInstrumentation, VERSION } = require('@grafana/faro-core');
+
+  class TracingInstrumentation extends BaseInstrumentation {
+    readonly name = '@grafana/faro-react-native-tracing';
+    readonly version = VERSION;
+    initialize(): void {}
+  }
+
+  return { TracingInstrumentation };
+});
+
+import { Platform } from 'react-native';
+
+import { TracingInstrumentation } from '@grafana/faro-react-native-tracing';
+
+import { ANRInstrumentation } from '../instrumentations/anr';
+import { AppStateInstrumentation } from '../instrumentations/appState';
+import { ConsoleInstrumentation } from '../instrumentations/console';
+import { CrashReportingInstrumentation } from '../instrumentations/crashReporting';
+import { ErrorsInstrumentation } from '../instrumentations/errors';
+import { FrameMonitoringInstrumentation } from '../instrumentations/frameMonitoring';
+import { HttpInstrumentation } from '../instrumentations/http';
+import { PerformanceInstrumentation } from '../instrumentations/performance';
+import { SessionInstrumentation } from '../instrumentations/session';
+import { StartupInstrumentation } from '../instrumentations/startup';
+import { UserActionInstrumentation } from '../instrumentations/userActions';
+import { ViewInstrumentation } from '../instrumentations/view';
+import { XHRInstrumentation } from '../instrumentations/xhr';
+
+import { getRNInstrumentations } from './getRNInstrumentations';
+
+/** Narrowing helper for `instanceof` against instrumentation classes (constructors use typed optional options). */
+function has(list: unknown[], Cls: abstract new (...args: any[]) => object): boolean {
+  return list.some((i) => i instanceof Cls);
+}
+
+describe('getRNInstrumentations', () => {
+  afterEach(() => {
+    jest.replaceProperty(Platform, 'OS', 'ios');
+  });
+
+  it('default flags include core instrumentations and HTTP when not tracing', () => {
+    const list = getRNInstrumentations({});
+
+    expect(has(list, ErrorsInstrumentation)).toBe(true);
+    expect(has(list, ConsoleInstrumentation)).toBe(true);
+    expect(has(list, SessionInstrumentation)).toBe(true);
+    expect(has(list, ViewInstrumentation)).toBe(true);
+    expect(has(list, AppStateInstrumentation)).toBe(true);
+    expect(has(list, UserActionInstrumentation)).toBe(true);
+    expect(has(list, HttpInstrumentation)).toBe(true);
+    expect(has(list, XHRInstrumentation)).toBe(true);
+    expect(has(list, PerformanceInstrumentation)).toBe(true);
+    expect(has(list, StartupInstrumentation)).toBe(true);
+
+    expect(has(list, FrameMonitoringInstrumentation)).toBe(false);
+    expect(has(list, CrashReportingInstrumentation)).toBe(false);
+    expect(has(list, ANRInstrumentation)).toBe(false);
+  });
+
+  it('omits ErrorsInstrumentation when enableErrorReporting is false', () => {
+    const list = getRNInstrumentations({ enableErrorReporting: false });
+    expect(has(list, ErrorsInstrumentation)).toBe(false);
+  });
+
+  it('omits ConsoleInstrumentation when enableConsoleCapture is false', () => {
+    const list = getRNInstrumentations({ enableConsoleCapture: false });
+    expect(has(list, ConsoleInstrumentation)).toBe(false);
+  });
+
+  it('omits UserActionInstrumentation when enableUserActions is false', () => {
+    const list = getRNInstrumentations({ enableUserActions: false });
+    expect(has(list, UserActionInstrumentation)).toBe(false);
+  });
+
+  it('respects enableHttpInstrumentation fetch/xhr toggles when tracing is off', () => {
+    const fetchOnly = getRNInstrumentations({
+      enableHttpInstrumentation: { fetch: true, xhr: false },
+    });
+    expect(has(fetchOnly, HttpInstrumentation)).toBe(true);
+    expect(has(fetchOnly, XHRInstrumentation)).toBe(false);
+
+    const xhrOnly = getRNInstrumentations({
+      enableHttpInstrumentation: { fetch: false, xhr: true },
+    });
+    expect(has(xhrOnly, HttpInstrumentation)).toBe(false);
+    expect(has(xhrOnly, XHRInstrumentation)).toBe(true);
+  });
+
+  it('adds FrameMonitoringInstrumentation when refreshRateVitals is true', () => {
+    const list = getRNInstrumentations({ refreshRateVitals: true });
+    expect(has(list, FrameMonitoringInstrumentation)).toBe(true);
+  });
+
+  it('adds CrashReportingInstrumentation when enableCrashReporting is true', () => {
+    const list = getRNInstrumentations({ enableCrashReporting: true });
+    expect(has(list, CrashReportingInstrumentation)).toBe(true);
+  });
+
+  it('adds ANRInstrumentation only on Android when anrTracking is true', () => {
+    jest.replaceProperty(Platform, 'OS', 'ios');
+    expect(has(getRNInstrumentations({ anrTracking: true }), ANRInstrumentation)).toBe(false);
+
+    jest.replaceProperty(Platform, 'OS', 'android');
+    expect(has(getRNInstrumentations({ anrTracking: true }), ANRInstrumentation)).toBe(true);
+  });
+
+  it('adds TracingInstrumentation and skips fetch/XHR instrumentations when enableTracing is true', () => {
+    const list = getRNInstrumentations({ enableTracing: true });
+    expect(has(list, TracingInstrumentation)).toBe(true);
+    expect(has(list, HttpInstrumentation)).toBe(false);
+    expect(has(list, XHRInstrumentation)).toBe(false);
+  });
+});

package/src/config/getRNInstrumentations.ts

@@ -0,0 +1,157 @@
+import { Platform } from 'react-native';
+
+import type { Instrumentation, Patterns } from '@grafana/faro-core';
+
+import { ANRInstrumentation } from '../instrumentations/anr';
+import { AppStateInstrumentation } from '../instrumentations/appState';
+import { ConsoleInstrumentation } from '../instrumentations/console';
+import { CrashReportingInstrumentation } from '../instrumentations/crashReporting';
+import { ErrorsInstrumentation } from '../instrumentations/errors';
+import { FrameMonitoringInstrumentation } from '../instrumentations/frameMonitoring';
+import { HttpInstrumentation } from '../instrumentations/http';
+import { PerformanceInstrumentation } from '../instrumentations/performance';
+import { SessionInstrumentation } from '../instrumentations/session';
+import { StartupInstrumentation } from '../instrumentations/startup';
+import { UserActionInstrumentation } from '../instrumentations/userActions';
+import { ViewInstrumentation } from '../instrumentations/view';
+import { XHRInstrumentation } from '../instrumentations/xhr';
+
+import type { ReactNativeConfig } from './types';
+
+/** Convert Patterns (string | RegExp)[] to RegExp[] for instrumentations that require RegExp[]. */
+function toRegExpArray(patterns: Patterns): RegExp[] {
+  return patterns.map((p) => (typeof p === 'string' ? new RegExp(p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')) : p));
+}
+
+/**
+ * Returns the default set of instrumentations for React Native.
+ *
+ * Reads all options from the Faro config (single source of truth).
+ * Property names are aligned with Flutter SDK FaroConfig:
+ * - cpuUsageVitals, memoryUsageVitals, anrTracking, refreshRateVitals
+ * - enableCrashReporting, enableErrorReporting
+ * - fetchVitalsInterval, ignoreUrls
+ *
+ * @example
+ * ```ts
+ * const config: ReactNativeConfig = {
+ *   app: { name: 'my-app', version: '1.0.0' },
+ *   cpuUsageVitals: true,
+ *   memoryUsageVitals: true,
+ *   anrTracking: true,
+ *   refreshRateVitals: true,
+ *   enableCrashReporting: true,
+ *   fetchVitalsInterval: 30000,
+ *   instrumentations: getRNInstrumentations(config),
+ * };
+ * ```
+ */
+export function getRNInstrumentations(config: Partial<ReactNativeConfig> = {}): Instrumentation[] {
+  // Aligned with Flutter SDK FaroConfig defaults
+  const {
+    // Error & crash tracking
+    enableErrorReporting = true,
+    enableCrashReporting = false,
+    anrTracking = false,
+    anrOptions = {},
+
+    // Performance vitals
+    cpuUsageVitals = true,
+    memoryUsageVitals = true,
+    refreshRateVitals = false,
+    fetchVitalsInterval = 30000,
+    frameMonitoringOptions = {},
+
+    // Network
+    ignoreUrls = [],
+    enableHttpInstrumentation = {},
+
+    // Console and user actions
+    enableConsoleCapture = true,
+    enableUserActions = true,
+
+    // Tracing
+    enableTracing = false,
+    tracingOptions = {},
+  } = config;
+
+  const instrumentations: Instrumentation[] = [];
+
+  // Error reporting (Flutter: enableFlutterErrorReporting)
+  if (enableErrorReporting) {
+    instrumentations.push(new ErrorsInstrumentation());
+  }
+
+  // Console capture - not in Flutter SDK, RN-specific
+  if (enableConsoleCapture) {
+    instrumentations.push(new ConsoleInstrumentation());
+  }
+
+  // Sessions - always enabled in Flutter, same here
+  instrumentations.push(new SessionInstrumentation());
+
+  // Views - always enabled in Flutter, same here
+  instrumentations.push(new ViewInstrumentation());
+
+  // App state - always enabled in Flutter, same here
+  instrumentations.push(new AppStateInstrumentation());
+
+  // User actions - enabled by default, opt-out via enableUserActions
+  if (enableUserActions) {
+    instrumentations.push(new UserActionInstrumentation());
+  }
+
+  // HTTP/XHR tracking: when tracing is enabled, TracingInstrumentation patches fetch and XHR.
+  // When tracing is disabled, add HttpInstrumentation and/or XHRInstrumentation per enableHttpInstrumentation.
+  if (!enableTracing) {
+    const { fetch: enableFetch = true, xhr: enableXhr = true } = enableHttpInstrumentation;
+    const ignoredUrlsRegExp = toRegExpArray(ignoreUrls);
+    if (enableFetch) {
+      instrumentations.push(new HttpInstrumentation({ ignoredUrls: ignoredUrlsRegExp }));
+    }
+    if (enableXhr) {
+      instrumentations.push(new XHRInstrumentation({ ignoredUrls: ignoredUrlsRegExp }));
+    }
+  }
+
+  // Performance vitals (CPU/memory)
+  const perfInstrumentation = new PerformanceInstrumentation({
+    memoryUsageVitals,
+    cpuUsageVitals,
+    fetchVitalsInterval,
+  });
+  instrumentations.push(perfInstrumentation);
+
+  // Startup tracking - always enabled
+  instrumentations.push(new StartupInstrumentation());
+
+  // Frame monitoring: enabled when refreshRateVitals is true
+  // The instrumentation reads refreshRateVitals from faro.config (single source of truth)
+  if (refreshRateVitals) {
+    instrumentations.push(new FrameMonitoringInstrumentation(frameMonitoringOptions));
+  }
+
+  // ANR detection (Android only)
+  if (anrTracking && Platform.OS === 'android') {
+    instrumentations.push(new ANRInstrumentation(anrOptions));
+  }
+
+  // Crash reporting
+  if (enableCrashReporting) {
+    instrumentations.push(new CrashReportingInstrumentation());
+  }
+
+  if (enableTracing) {
+    try {
+      const { TracingInstrumentation } = require('@grafana/faro-react-native-tracing');
+      instrumentations.push(new TracingInstrumentation(tracingOptions));
+    } catch {
+      console.warn(
+        '[Faro] enableTracing is true but @grafana/faro-react-native-tracing is not installed. ' +
+          'Add it to use tracing: yarn add @grafana/faro-react-native-tracing'
+      );
+    }
+  }
+
+  return instrumentations;
+}

package/src/config/makeRNConfig.test.ts

@@ -0,0 +1,117 @@
+import { BaseInstrumentation, VERSION } from '@grafana/faro-core';
+
+import { defaultSessionTrackingConfig } from '../instrumentations/session/sessionManager/sessionConstants';
+import { ConsoleTransport } from '../transports/console';
+import { FetchTransport } from '../transports/fetch';
+import { OfflineTransport } from '../transports/offline';
+
+import { getRNInstrumentations } from './getRNInstrumentations';
+import { makeRNConfig } from './makeRNConfig';
+import type { ReactNativeConfig } from './types';
+
+class ExtraInstrumentation extends BaseInstrumentation {
+  readonly name = '@test/extra-instrumentation';
+  readonly version = VERSION;
+
+  initialize(): void {}
+}
+
+function disposeOfflineTransportsFromConfig(cfg: { transports?: unknown[] }): void {
+  for (const t of cfg.transports ?? []) {
+    if (t instanceof OfflineTransport) {
+      t.dispose();
+    }
+  }
+}
+
+describe('makeRNConfig', () => {
+  const base: Pick<ReactNativeConfig, 'app' | 'url'> = {
+    app: { name: 'test-app', version: '1.0.0' },
+    url: 'https://faro.example.com/collect',
+  };
+
+  it('throws when url is missing', () => {
+    expect(() =>
+      makeRNConfig({
+        app: base.app,
+      } as ReactNativeConfig)
+    ).toThrow('url is required');
+  });
+
+  it('builds OfflineTransport, FetchTransport, and optional ConsoleTransport in order', () => {
+    const offlineFirst = makeRNConfig({
+      ...base,
+      enableTransports: { offline: true, console: false },
+    });
+    try {
+      expect(offlineFirst.transports?.[0]).toBeInstanceOf(OfflineTransport);
+      expect(offlineFirst.transports?.[1]).toBeInstanceOf(FetchTransport);
+
+      const withConsole = makeRNConfig({
+        ...base,
+        enableTransports: { offline: true, console: true },
+      });
+      try {
+        expect(withConsole.transports?.[0]).toBeInstanceOf(OfflineTransport);
+        expect(withConsole.transports?.[1]).toBeInstanceOf(FetchTransport);
+        expect(withConsole.transports?.[2]).toBeInstanceOf(ConsoleTransport);
+      } finally {
+        disposeOfflineTransportsFromConfig(withConsole);
+      }
+    } finally {
+      disposeOfflineTransportsFromConfig(offlineFirst);
+    }
+  });
+
+  it('defaults to FetchTransport only when enableTransports omitted', () => {
+    const cfg = makeRNConfig({ ...base });
+    expect(cfg.transports).toHaveLength(1);
+    expect(cfg.transports?.[0]).toBeInstanceOf(FetchTransport);
+  });
+
+  it('appends extra transports after built-ins', () => {
+    const marker = { transport: 'extra' } as unknown as NonNullable<ReactNativeConfig['transports']>[number];
+    const cfg = makeRNConfig({
+      ...base,
+      enableTransports: { console: true },
+      transports: [marker],
+    });
+    expect(cfg.transports?.[0]).toBeInstanceOf(FetchTransport);
+    expect(cfg.transports?.[1]).toBeInstanceOf(ConsoleTransport);
+    expect(cfg.transports?.[2]).toBe(marker);
+  });
+
+  it('appends extra instrumentations after getRNInstrumentations', () => {
+    const extra = new ExtraInstrumentation();
+    const cfg = makeRNConfig({
+      ...base,
+      instrumentations: [extra],
+    });
+    const names = cfg.instrumentations?.map((i) => i.name) ?? [];
+    expect(names.at(-1)).toBe(extra.name);
+  });
+
+  it('merges sessionTracking defaults with user overrides', () => {
+    const cfg = makeRNConfig({
+      ...base,
+      sessionTracking: {
+        persistent: true,
+      },
+    });
+    expect(cfg.sessionTracking).toMatchObject({
+      ...defaultSessionTrackingConfig,
+      persistent: true,
+    });
+  });
+
+  it('uses getRNInstrumentations for the instrumentation set from flags', () => {
+    const minimal = makeRNConfig({
+      ...base,
+      enableErrorReporting: false,
+    });
+    const direct = getRNInstrumentations({ enableErrorReporting: false });
+
+    expect(minimal.instrumentations?.length).toBe(direct.length);
+    expect(minimal.instrumentations?.map((i) => i.name)).toEqual(direct.map((i) => i.name));
+  });
+});