Skip to main content

​
expo-background-fetch

Version: 55.0.6 Expo universal module for BackgroundFetch API. Allows you to register background tasks that run periodically even when the app is closed or in the background.

​
Installation

npx expo install expo-background-fetch expo-task-manager

​
Usage

import * as BackgroundFetch from 'expo-background-fetch';
import * as TaskManager from 'expo-task-manager';

const BACKGROUND_FETCH_TASK = 'background-fetch-task';

// Define task
TaskManager.defineTask(BACKGROUND_FETCH_TASK, async () => {
  const now = Date.now();
  console.log(`Background fetch executed at ${new Date(now).toISOString()}`);
  
  // Perform your background work here
  await fetchDataFromAPI();
  
  return BackgroundFetch.BackgroundFetchResult.NewData;
});

// Register task
async function registerBackgroundFetch() {
  return BackgroundFetch.registerTaskAsync(BACKGROUND_FETCH_TASK, {
    minimumInterval: 60 * 15, // 15 minutes
    stopOnTerminate: false,
    startOnBoot: true,
  });
}

​
API Reference

​
Methods

​
registerTaskAsync(taskName, options)
(taskName: string, options?: BackgroundFetchOptions) => Promise<void>
Registers a background fetch task
await BackgroundFetch.registerTaskAsync('my-task', {
  minimumInterval: 900, // 15 minutes in seconds
});
​
unregisterTaskAsync(taskName)
(taskName: string) => Promise<void>
Unregisters a background fetch task
await BackgroundFetch.unregisterTaskAsync('my-task');
​
getStatusAsync()
() => Promise<BackgroundFetchStatus>
Gets background fetch status
const status = await BackgroundFetch.getStatusAsync();
console.log('Status:', status);
​
setMinimumIntervalAsync(seconds)
(seconds: number) => Promise<void>
Sets minimum fetch interval (iOS only)
await BackgroundFetch.setMinimumIntervalAsync(60 * 30); // 30 minutes

​
Types

​
BackgroundFetchOptions

​
minimumInterval
number
Minimum interval in seconds between fetches. Default: 900 (15 min)
​
stopOnTerminate
boolean
Whether to stop task when app is terminated. Default: true
​
startOnBoot
boolean
Whether to start task on device boot (Android). Default: false

​
BackgroundFetchResult

enum BackgroundFetchResult {
  NoData = 1,
  NewData = 2,
  Failed = 3,
}

​
Examples

​
Sync Data in Background

import * as BackgroundFetch from 'expo-background-fetch';
import * as TaskManager from 'expo-task-manager';

const SYNC_TASK = 'background-sync';

TaskManager.defineTask(SYNC_TASK, async () => {
  try {
    // Fetch new data
    const response = await fetch('https://api.example.com/data');
    const data = await response.json();
    
    // Store locally
    await AsyncStorage.setItem('cached-data', JSON.stringify(data));
    
    return BackgroundFetch.BackgroundFetchResult.NewData;
  } catch (error) {
    console.error('Background sync failed:', error);
    return BackgroundFetch.BackgroundFetchResult.Failed;
  }
});

// Register on app start
async function setupBackgroundSync() {
  const status = await BackgroundFetch.getStatusAsync();
  
  if (status === BackgroundFetch.BackgroundFetchStatus.Available) {
    await BackgroundFetch.registerTaskAsync(SYNC_TASK, {
      minimumInterval: 60 * 60, // 1 hour
    });
  }
}

​
Platform Support

PlatformSupported
iOS✅
Android✅
Web❌

​
Configuration

​
app.json

{
  "expo": {
    "plugins": [
      [
        "expo-background-fetch",
        {
          "android": {
            "minInterval": 15
          }
        }
      ]
    ]
  }
}

​
Best Practices

  1. Battery Efficiency: Keep background tasks short
  2. Minimum Interval: Respect system-imposed minimum intervals
  3. Error Handling: Always handle errors gracefully
  4. Return Values: Return appropriate BackgroundFetchResult
  5. Testing: Test on real devices, not simulators
Background fetch intervals are not guaranteed. The system may adjust intervals based on battery, usage patterns, and other factors.

​
Resources