{"id":18325,"library":"expo-background-fetch","title":"expo-background-fetch","description":"Provides a universal API for performing background fetch tasks in Expo and React Native apps, allowing periodic data fetching even when the app is in the background. Current stable version is 55.0.15, updated alongside the Expo SDK release cycle (roughly quarterly). Key differentiators: built on top of iOS BGTaskScheduler and Android WorkManager for reliable execution, integrated with Expo's manifest and permissions system. Unlike bare React Native plugins, handles Expo managed workflow and development builds seamlessly. Supports minimum interval configuration and status callbacks.","status":"active","version":"55.0.15","language":"javascript","source_language":"en","source_url":"https://github.com/expo/expo","tags":["javascript","expo","react-native","fetch","background","background-fetch","typescript"],"install":[{"cmd":"npm install expo-background-fetch","lang":"bash","label":"npm"},{"cmd":"yarn add expo-background-fetch","lang":"bash","label":"yarn"},{"cmd":"pnpm add expo-background-fetch","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for Expo module system integration.","package":"expo","optional":false}],"imports":[{"note":"ESM-only; CommonJS require will fail in Expo's module resolution.","wrong":"const BackgroundFetch = require('expo-background-fetch')","symbol":"BackgroundFetch","correct":"import * as BackgroundFetch from 'expo-background-fetch'"},{"note":"Import specific types/constants as named exports from the module.","wrong":"import { BackgroundFetch } from 'expo-background-fetch' // BackgroundFetch is namespace, not a named export","symbol":"BackgroundFetch.BackgroundFetchStatus","correct":"import { BackgroundFetchStatus } from 'expo-background-fetch'"},{"note":"Recommended to destructure for clarity.","wrong":"BackgroundFetch.registerTaskAsync('task', {...}) // valid but can be destructured","symbol":"registerTaskAsync","correct":"import { registerTaskAsync } from 'expo-background-fetch'"},{"note":"TypeScript type for task result (NoData, NewData, Failed).","wrong":"","symbol":"BackgroundFetchResult","correct":"import { BackgroundFetchResult } from 'expo-background-fetch'"}],"quickstart":{"code":"import * as BackgroundFetch from 'expo-background-fetch';\nimport * as TaskManager from 'expo-task-manager';\n\nconst BACKGROUND_FETCH_TASK = 'background-fetch-task';\n\nTaskManager.defineTask(BACKGROUND_FETCH_TASK, async () => {\n  try {\n    const response = await fetch('https://example.com/data');\n    const data = await response.json();\n    console.log('Background fetch data:', data);\n    return BackgroundFetch.BackgroundFetchResult.NewData;\n  } catch (error) {\n    console.error('Background fetch failed:', error);\n    return BackgroundFetch.BackgroundFetchResult.Failed;\n  }\n});\n\nasync function registerFetchTask() {\n  const status = await BackgroundFetch.getStatusAsync();\n  if (status === BackgroundFetch.BackgroundFetchStatus.Available) {\n    await BackgroundFetch.registerTaskAsync(BACKGROUND_FETCH_TASK, {\n      minimumInterval: 15 * 60, // 15 minutes in seconds\n      stopOnTerminate: false,\n      startOnBoot: true,\n    });\n  }\n}\n\nregisterFetchTask();","lang":"typescript","description":"Defines a background fetch task, registers it with a minimum interval, and handles fetch results (NewData/Failed)."},"warnings":[{"fix":"Set minimumInterval to at least 15 minutes (900 seconds); test on a real device.","message":"Background fetch on iOS requires the 'background fetch' capability and may be throttled by iOS. Minimum interval is not guaranteed.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Replace BackgroundFetch.eventName with string literals for task names.","message":"expo-background-fetch 11.0.0 removed the 'BackgroundFetch.eventName' export. Use task names directly.","severity":"breaking","affected_versions":">=11.0.0"},{"fix":"Use TaskManager.defineTask() and BackgroundFetch.registerTaskAsync() instead.","message":"BackgroundFetch.configureAsync() is deprecated in favor of registerTaskAsync().","severity":"deprecated","affected_versions":">=8.0.0"},{"fix":"Inform users that background tasks may be killed by the OS; use WorkManager for more control.","message":"Android background fetch may not work if app is force-stopped; startOnBoot only re-registers after reboot.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add 'plugins': ['expo-background-fetch'] to app.json.","message":"Expo SDK 44+ requires app.json with 'backgroundFetch' plugin for Android.","severity":"breaking","affected_versions":">=44.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Replace 'import BackgroundFetch from ...' with 'import * as BackgroundFetch from ...'","cause":"Using default import instead of namespace import.","error":"TypeError: Cannot read properties of undefined (reading 'BackgroundFetchResult')"},{"fix":"Test on a real device or use Expo's development build with a physical device.","cause":"Background fetch is not supported on iOS simulator.","error":"BackgroundFetchStatus not available on iOS simulator"},{"fix":"Call TaskManager.defineTask(taskName, handler) before BackgroundFetch.registerTaskAsync().","cause":"Trying to register a task without defining it first.","error":"Task 'background-fetch-task' is not defined. Use TaskManager.defineTask to define it."},{"fix":"Ensure the task is registered with proper options and the device is not in low power mode.","cause":"Background fetch task may be interrupted by iOS/Android.","error":"Background timer is not running because the app is in the background and the background task has been suspended."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}