react-native-background-runtime

Production-grade background execution framework for React Native with Android 12+ and iOS 16+ support.

Key Capabilities

• New Architecture-friendly bridge design (TurboModule-ready + event emission)
• Android foreground service + WorkManager + AlarmManager fallback + boot recovery hooks
• iOS BGTaskScheduler and Background Fetch integration points
• Heartbeat/watchdog events, state persistence, retry policy primitives, and metrics contract
• TypeScript-first API with strict runtime validation

Install

npm install react-native-background-runtime

Basic Usage

import { BackgroundRuntime } from 'react-native-background-runtime';

await BackgroundRuntime.configure({
  android: {
    foregroundService: true,
    autoRestart: true,
    notification: {
      title: 'Background Service',
      text: 'Running'
    }
  },
  ios: {
    backgroundFetch: true,
    bgProcessing: true
  }
});

await BackgroundRuntime.start();

const sub = BackgroundRuntime.on('heartbeat', (event) => {
  console.log('Heartbeat', event.timestamp);
});

// Later
sub.remove();
await BackgroundRuntime.stop();

iOS Limitation Notice

This library does not and cannot guarantee continuous execution on iOS. Apple controls when and how long background work can run. The framework maximizes opportunities through compliant mechanisms (BGTaskScheduler, Background Fetch, silent push triggers), but execution windows remain system-managed.

Development

npm run build --workspace react-native-background-runtime
npm run typecheck --workspace react-native-background-runtime
npm run test --workspace react-native-background-runtime