{"id":11791,"library":"react-native-performance","title":"React Native Performance API","description":"react-native-performance is a library that brings a comprehensive implementation of the Web Performance API (User Timing Level 3 and Performance Timeline Level 2) to React Native applications. It provides high-resolution, monotonically increasing timestamps for accurate measurement, independent of system clock adjustments. The current stable version is 6.0.0, released in late 2024. The project maintains an active release cadence with frequent patch and minor updates, and major versions introducing breaking changes every few months. Key differentiators include its adherence to web standards, support for custom metrics, optional network resource logging (for fetch/XMLHttpRequest), and native marks for measuring core application startup and lifecycle events. It also offers the PerformanceObserver API for subscribing to performance entries and ships with full TypeScript type definitions.","status":"active","version":"6.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/oblador/react-native-performance","tags":["javascript","react-native","performance","perf","benchmark","typescript"],"install":[{"cmd":"npm install react-native-performance","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-performance","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-performance","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required runtime peer dependency for all React Native features.","package":"react-native","optional":false}],"imports":[{"note":"The main performance API object is a default export.","wrong":"import { performance } from 'react-native-performance';","symbol":"performance","correct":"import performance from 'react-native-performance';"},{"note":"PerformanceObserver is a named export for event-driven performance entry monitoring.","wrong":"import PerformanceObserver from 'react-native-performance';","symbol":"PerformanceObserver","correct":"import { PerformanceObserver } from 'react-native-performance';"},{"note":"This utility function for resource logging is a named export, not a method on the default 'performance' object.","wrong":"performance.setResourceLoggingEnabled(true);","symbol":"setResourceLoggingEnabled","correct":"import { setResourceLoggingEnabled } from 'react-native-performance';"},{"note":"While primarily used in ESM, CommonJS environments require accessing the default export via `.default` and named exports directly.","symbol":"All common imports (CJS)","correct":"const performance = require('react-native-performance').default;\nconst { PerformanceObserver, setResourceLoggingEnabled } = require('react-native-performance');"}],"quickstart":{"code":"import performance, { PerformanceObserver, setResourceLoggingEnabled } from 'react-native-performance';\n\n// Enable resource logging early in your app lifecycle if needed\nsetResourceLoggingEnabled(true);\n\n// Observe performance measures and resources\nconst perfObserver = new PerformanceObserver((list) => {\n  list.getEntries().forEach((entry) => {\n    console.log(`[PerfEntry] ${entry.entryType}: ${entry.name} took ${entry.duration.toFixed(2)}ms`);\n    if (entry.entryType === 'resource') {\n      console.log(`  - URL: ${entry.name}, Transfer Size: ${entry.transferSize} bytes`);\n    }\n  });\n});\nperfObserver.observe({ entryTypes: ['measure', 'resource', 'metric'], buffered: true });\n\nasync function simulateOperation() {\n  performance.mark('opStart', { detail: { type: 'apiCall', screen: 'home' } });\n  console.log('Fetching data...');\n  try {\n    const response = await fetch('https://jsonplaceholder.typicode.com/todos/1');\n    const data = await response.json();\n    console.log('Data fetched:', data.title);\n    performance.mark('opEnd');\n    performance.measure('fetchDataOperation', 'opStart', 'opEnd', { detail: { status: 'success' } });\n  } catch (error) {\n    console.error('Fetch failed:', error);\n    performance.mark('opEnd');\n    performance.measure('fetchDataOperation', 'opStart', 'opEnd', { detail: { status: 'failed', error: String(error) } });\n  }\n  performance.metric('customMetricExample', Math.floor(Math.random() * 100));\n}\n\nsimulateOperation();\n\n// Example of converting performance timestamp to Unix epoch (optional)\n// const timestamp = Date.now() - performance.timeOrigin + performance.now();\n// console.log(`Current Unix epoch from performance: ${timestamp}`);","lang":"typescript","description":"This quickstart demonstrates marking, measuring, custom metrics, network resource logging, and observing performance entries using `PerformanceObserver` with detailed metadata."},"warnings":[{"fix":"Review your native module integration and update to the new API methods and codegen setup. Remove any Flipper-related performance code.","message":"Version 6.0.0 removed support for several long-deprecated APIs and features, including Flipper integration, Flow-based Codegen (now TypeScript), and replaced `onCatalystInstanceDestroyed` with `invalidate` and `hasActiveCatalystInstance` with `hasActiveReactInstance`.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"No direct code fix needed for consumers, but be aware that native startup time metrics might reflect different values compared to previous versions due to the improved measurement accuracy.","message":"Version 5.0.0 introduced a new approach to measuring native startup time on iOS to prevent distorted or excessively high measurements, particularly on iOS 15+.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure your React Native version is 0.68.3 or newer when upgrading to react-native-performance v4.0.0+. Older versions might not be compatible.","message":"Version 4.0.0 made a breaking change where `react-native-performance` native marks switched back to using a monotonic clock. This change was necessary to support React Native 0.68.3 and above.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Use `const unixTimestamp = Date.now() - performance.timeOrigin + entry.startTime;` for accurate conversions.","message":"Performance timestamps are high-resolution and monotonically increasing, meaning they are independent of system clock adjustments. To convert a performance timestamp to a Unix epoch timestamp, you must subtract `performance.timeOrigin` from `Date.now()` and then add the performance entry's `startTime`.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Call `setResourceLoggingEnabled(true);` early in your application's lifecycle to activate resource logging.","message":"Network resource logging is disabled by default and only covers `fetch`/`XMLHttpRequest` uses within React Native. It will not capture native network requests unless explicitly enabled.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade to `react-native-performance` version 6.0.0 or later, which includes a fix for this specific Android issue.","cause":"Timing issue on Android where the native module attempts to interact with JavaScript before it's fully ready.","error":"Soft exception when library tries to access `RCTDeviceEventEmitter` before it is initialized."},{"fix":"Upgrade to `react-native-performance` version 5.1.4 or later, which contains fixes for bridgeless mode on both iOS and Android.","cause":"Compatibility issues with the experimental bridgeless mode, often related to native module communication.","error":"Errors or unexpected behavior when running in React Native's bridgeless mode."},{"fix":"Upgrade to `react-native-performance` version 5.1.3 or later, which addresses a build failure on iOS related to custom native marks.","cause":"Issues with Xcode or Cocoapods configuration when integrating custom native marks.","error":"iOS build failure when using custom native marks."},{"fix":"Ensure you are using `import { PerformanceObserver } from 'react-native-performance';` and not a default import for `PerformanceObserver`.","cause":"`PerformanceObserver` was not correctly imported as a named export, or the import statement for `react-native-performance` is incorrect.","error":"TypeError: Cannot read property 'observe' of undefined (or 'PerformanceObserver is not a constructor')"}],"ecosystem":"npm"}