Registry / messaging / react-native-background-fetch

react-native-background-fetch

library4.4.2jsnpmunverified

Background fetch is a React Native module that provides periodic background data fetching on iOS and Android. Current stable version is 4.4.2. It leverages native APIs (iOS BGTaskScheduler, Android JobScheduler/AlarmManager) to schedule minimal background tasks, not guaranteed to run at fixed intervals. Key differentiators: reliable cross-platform API, support for headless JS tasks, Expo config plugin, and TypeScript types. Alternative to react-native-background-actions but more battery-friendly.

messaging

npm install react-native-background-fetch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-NATIVE-BACKG

react-native-background-fetch

messagingjavascriptv4.4.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

BackgroundFetch

✓ import BackgroundFetch from 'react-native-background-fetch'

✗ import { BackgroundFetch } from 'react-native-background-fetch'

Default export, not named. ESM/CJS compatible.

BackgroundFetchEvent

✓ import type { BackgroundFetchEvent } from 'react-native-background-fetch'

✗ import { BackgroundFetchEvent } from 'react-native-background-fetch'

Type-only import for TypeScript.

configure

✓ import BackgroundFetch from 'react-native-background-fetch'; BackgroundFetch.configure(...)

✗ import { configure } from 'react-native-background-fetch'

configure is a method on the default export.

Configures background fetch with a 15-minute minimum interval and headless JS support.

import BackgroundFetch from 'react-native-background-fetch'; async function init() { const status = await BackgroundFetch.configure( { minimumFetchInterval: 15, // minutes stopOnTerminate: false, startOnBoot: true, enableHeadless: true, }, async (taskId: string) => { console.log('[BackgroundFetch] task:', taskId); // Perform background work BackgroundFetch.finish(taskId); }, (taskId: string) => { console.log('[BackgroundFetch] timeout:', taskId); BackgroundFetch.finish(taskId); } ); console.log('BackgroundFetch status:', status); } init(); export {};

Debug

Known issues

breakingv3.x changed from RNNativeModules to TurboModules for iOS; manual linking required for RN < 0.68

fix

For RN < 0.68, use react-native link or CocoaPods. Upgrade to v4 for RN 0.68+ autolinking.

affects: >=3.0.0 <4.0.0

gotchaOn iOS, minimumFetchInterval is not respected exactly; iOS determines the actual interval based on user patterns.

fix

Do not rely on exact intervals; assume background fetch may be delayed or combined.

affects: >=1.0.0

deprecatedBackgroundFetch.configure with callback as second param is deprecated in favor of event-based API using BackgroundFetch.on.

fix

Use BackgroundFetch.on('fetch', callback) instead.

affects: >=4.0.0

gotchaAndroid requires scheduling using JobScheduler; devices with aggressive battery optimization may delay tasks.

fix

Add device-specific battery optimization whitelist instructions in docs.

affects: >=1.0.0

breakingv4.0.0 switched from Default import to ES Module import; require() breaks.

fix

Use import BackgroundFetch from 'react-native-background-fetch' instead of const BackgroundFetch = require('react-native-background-fetch').

affects: >=4.0.0

gotchaBackgroundFetch.finish() must be called within the event handler to prevent iOS termination warnings.

fix

Always call BackgroundFetch.finish(taskId) after async work.

affects: >=1.0.0

deprecatedBackgroundFetch.status() is deprecated in v4; use the result from configure() or BackgroundFetch.getStatus().

fix

Use configure() return value or BackgroundFetch.getStatus() API.

affects: >=4.0.0

Errors

Common errors & fixes

BackgroundFetch is not a function

Importing { BackgroundFetch } incorrectly as named export instead of default.

fix

Use: import BackgroundFetch from 'react-native-background-fetch'

Native module cannot be found: BackgroundFetch

Native side not linked properly (RN < 0.68) or missing pod install.

fix

Run: cd ios && pod install && cd .. . For RN < 0.68, also run: react-native link react-native-background-fetch

The method 'finish' is not a function

Using BackgroundFetch.finish before configure or on event, or incorrect import.

fix

Ensure BackgroundFetch is imported as default and finish is called within event handler after work.

Task 'myTask' already registered

Trying to register a task with the same identifier twice.

fix

Use unique task IDs or call BackgroundFetch.stop(taskId) before re-registering.

Expo Config Plugin: 'react-native-background-fetch' requires '@expo/config-plugins' >= 10.0.0

Missing or outdated Expo config-plugins dependency.

fix

npm install @expo/config-plugins@>=10.0.0

Upgrade

Version history

4.4.2latest on npm

Audit

Dependencies

@expo/config-pluginsoptionalRequired for Expo managed workflow configuration

Agent activity

16 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubssh://git@github.com/transistorsoft/react-native-background-fetch ↗

packagereact-native-background-fetch ↗

homepagehttps://transistorsoft.github.io/react-native-background-fetch ↗