react-native-device-pulse

Monitor device health from React Native: thermal state, low power mode and memory warnings, with event subscriptions and React hooks. Built as a New Architecture TurboModule with synchronous getters.

Why

Phones throttle. When a device heats up, the OS silently cuts CPU/GPU frequencies and your beautiful 60 fps animation becomes a 20 fps slideshow — while draining the battery even faster. The platforms tell you this is happening (NSProcessInfo.thermalState on iOS, PowerManager thermal status on Android), but that signal rarely makes it into React Native apps.

react-native-device-pulse surfaces those signals so you can adapt quality instead of fighting the hardware:

• Drop video resolution or animation complexity when the device gets hot.
• Pause prefetching and background sync while Battery Saver / Low Power Mode is on.
• Free caches when the OS says memory is running low, before it kills you.

See docs/adaptive-performance.md for the pattern.

Installation

npm install react-native-device-pulse
# or
yarn add react-native-device-pulse

The library autolinks — no manual native setup. iOS needs a pod install in your app as usual. The New Architecture is required (it is the default since React Native 0.76).

Quick start

import {
  useThermalState,
  useLowPowerMode,
  useMemoryWarning,
} from 'react-native-device-pulse';

function VideoPlayer() {
  const thermalState = useThermalState(); // 'nominal' | 'fair' | 'serious' | 'critical' | 'unknown'
  const lowPower = useLowPowerMode(); // boolean

  useMemoryWarning(() => {
    imageCache.clear();
  });

  const quality =
    thermalState === 'serious' || thermalState === 'critical' || lowPower
      ? '480p'
      : '1080p';

  return <Player quality={quality} />;
}

Or without hooks:

import {
  getThermalState,
  isLowPowerMode,
  addThermalStateListener,
} from 'react-native-device-pulse';

console.log(getThermalState()); // synchronous, e.g. 'nominal'
console.log(isLowPowerMode()); // synchronous, e.g. false

const subscription = addThermalStateListener((state) => {
  console.log('thermal state is now', state);
});
// later
subscription.remove();

API

Full reference with platform notes: docs/API.md.

| Export | Type | Description | | --- | --- | --- | | getThermalState() | () => ThermalState | Current thermal state, synchronously. | | isLowPowerMode() | () => boolean | Whether Low Power Mode (iOS) / Battery Saver (Android) is on, synchronously. | | addThermalStateListener(cb) | (cb: (state: ThermalState) => void) => EmitterSubscription | Subscribe to thermal state changes. | | addLowPowerModeListener(cb) | (cb: (enabled: boolean) => void) => EmitterSubscription | Subscribe to Low Power Mode / Battery Saver changes. | | addMemoryWarningListener(cb) | (cb: () => void) => EmitterSubscription | Subscribe to system memory warnings. | | useThermalState() | () => ThermalState | Hook: live thermal state. | | useLowPowerMode() | () => boolean | Hook: live Low Power Mode state. | | useMemoryWarning(cb) | (cb: () => void) => void | Hook: run cb on every memory warning. | | ThermalState | 'nominal' \| 'fair' \| 'serious' \| 'critical' \| 'unknown' | Thermal state union type. | | DevicePulseEvents | object | The raw native event names, if you need them. |

Platform support

| Feature | iOS | Android | | --- | --- | --- | | Thermal state | ✅ (NSProcessInfo.thermalState) | ✅ API 29+ (PowerManager thermal status); below API 29 returns 'unknown' and emits no events | | Low power mode | ✅ Low Power Mode | ✅ Battery Saver (isPowerSaveMode) | | Memory warnings | ✅ UIApplicationDidReceiveMemoryWarningNotification | ✅ onTrimMemory at memory-pressure levels |

Thermal mapping on Android: NONE → nominal, LIGHT/MODERATE → fair, SEVERE → serious, CRITICAL/EMERGENCY/SHUTDOWN → critical.

Example app

The example app is a small live dashboard: a color-coded thermal card, a Low Power Mode badge and a timestamped memory warning log.

yarn
yarn example ios     # or: yarn example android

Tips for exercising it:

• iOS simulator: Device → Simulate Memory Warning; toggle Low Power Mode on a real device in Settings → Battery.
• Android emulator: enable Battery Saver from the quick settings, or adb shell settings put global low_power 1; simulate thermal status with adb shell cmd thermalservice override-status 2.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT © Bao Nguyen

Made with create-react-native-library