# react-native-background-fetch for Periodic Mobile Work > react-native-background-fetch is a React Native plugin for receiving periodic background callbacks on iOS and Android. It is best suited to best-effort synchronization and scheduled maintenance, not workloads that require exact execution times. **transistorsoft/react-native-background-fetch** — Periodic callbacks in the background for both IOS and Android - Repository: https://github.com/transistorsoft/react-native-background-fetch - Stars: 1,611 · Forks: 196 - Language: Java - License: MIT - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/transistorsoft-react-native-background-fetch ## Periodic callbacks for best-effort mobile work react-native-background-fetch addresses a specific React Native limitation: running a supplied `callbackFn` while an application is in the background. It targets both iOS and Android, so an application can define periodic work without replacing that work with a separate platform-specific scheduling system. The intended workload is opportunistic. The plugin attempts to awaken an app about every 15 minutes and then provides a short period in which the callback can run. That description should not be read as a service-level schedule. The README says the operating system throttles event frequency according to usage patterns. A phone that has not been used for a long time may receive fewer events, and an iOS user who disables background refresh may receive none. This makes the project more suitable for synchronization, cache maintenance, or other work that can run later. It is a poor fit for billing deadlines, alarm delivery, polling that must happen every few minutes, or any workflow where a missed event creates a user-visible or data-consistency failure. The callback is a chance to perform work, not a guarantee that the operating system will schedule it at a particular time. ## One-shot and periodic tasks through `scheduleTask` The newer `scheduleTask` method expands the plugin beyond its recurring background-fetch callback. The README describes it as a way to schedule arbitrary one-shot or periodic tasks. That distinction matters for applications whose jobs have different scheduling semantics. A recurring fetch can represent routine maintenance, while a one-shot task can represent work that should be attempted once at a later point. The underlying constraint remains platform control. The plugin cannot force iOS or Android to execute work on an exact date or at an exact interval. The README specifically warns that `scheduleTask` on iOS seems to fire only when the device is plugged into power. That makes it unsuitable as a general-purpose timer for users who run their phones on battery. The API documentation is hosted outside the README, and the README links to the `scheduleTask` documentation rather than reproducing its full configuration. The repository includes TypeScript declarations through `index.d.ts`, while `src/` and `index.js` provide the JavaScript-facing implementation. The documented method name is clear, but an adopter still needs the linked API reference to determine the exact task parameters and callback behavior before designing production scheduling around it. ## Android HeadlessJS and terminated-app behavior On Android, the plugin provides a HeadlessJS implementation. According to the README, this allows event handling to continue even after app termination when `enableHeadless` is configured. This is the clearest platform distinction in the project. Android can offer a path for processing background events outside a normal visible application session, although the exact configuration is defined in the separate API documentation. HeadlessJS should be treated as a processing arrangement, not as permission to execute unlimited work. The background-fetch mechanism is still periodic and subject to the operating system's scheduling decisions. The callback should therefore be designed to be short, safe to retry, and tolerant of partial completion. The README does not document a transaction protocol, retry policy, or persistence contract for scheduled tasks, so those behaviors should not be assumed. iOS has a stricter boundary. The README states that when the app is terminated, iOS no longer fires events and that there is no iOS equivalent of `stopOnTerminate: false`. It also warns that iOS can take days before Apple’s scheduling algorithm settles into a regular pattern. A callback can therefore be configured correctly and still appear absent during initial observation. The README advises checking simulated events as a configuration signal, rather than waiting for a natural event as the only proof of setup. ## Installing through Expo, Yarn, or npm The README provides three installation paths. Choose the one that matches the package manager used by the React Native application. The Expo command is intended for an Expo project, while Yarn and npm are documented as direct package-manager alternatives. For an Expo project, run: ```bash npx expo install react-native-background-fetch ``` For a Yarn project, run: ```bash yarn add react-native-background-fetch ``` For an npm project, run: ```bash npm install --save react-native-background-fetch ``` After installation, the README directs developers to the external Setup Guide for native configuration. It does not provide a complete first-use snippet in the repository README, so the first real use begins by following that setup guide, registering the documented `callbackFn`, and confirming the platform-specific configuration. The API Documentation is the source for the current configuration keys and method signatures. The repository also contains an `example/` directory and an Expo example path, which can provide an application-level starting point without requiring an invented configuration example. ## Why the 15-minute interval is not a deadline The central design tradeoff is visible in the README’s language: the plugin sets the most frequent possible recurring rate, while explicitly stating that no event can arrive faster than 15 minutes. Even that wording does not turn the interval into a guarantee. Operating-system throttling changes the actual timing. On iOS, several documented conditions can reduce delivery: background refresh may be disabled, the app may remain unopened for long periods, or the system may take days to establish a regular pattern. The plugin also stops receiving events when the iOS app is terminated. On Android, HeadlessJS can continue handling events after app termination, but the same need to respect a short execution window remains. A real implementation should use the callback as an opportunity to inspect pending work and do bounded work, rather than assuming that every elapsed interval corresponds to exactly one callback. The README does not specify how missed intervals are reported, whether callbacks overlap, or how long a callback may run. Those points need to be verified against the linked documentation and, where necessary, the behavior of the target mobile OS. This is a meaningful difference from libraries designed around user-created timers, which are better for precise in-app intervals but do not provide the same background-awakening model. ## Maintenance, package structure, and MIT licensing The repository is not archived. Its last push was on 2026-04-22, so it has a recent recorded development change based on the repository metadata. There are no GitHub releases listed, so users should not assume that a release stream or a formal upgrade policy exists. The package manifest identifies version `4.4.2` and exposes TypeScript types through `index.d.ts`. It also declares a dependency on `@transistorsoft/background-fetch-types` and an optional peer dependency on `@expo/config-plugins`. The package includes native directories for Android and iOS, a podspec named `RNBackgroundFetch.podspec`, JavaScript sources under `src/`, and an Expo configuration plugin. Those entries indicate that adoption involves more than copying a JavaScript utility. Native project integration, OS behavior, and app-level task design all matter when upgrading. The repository’s `CHANGELOG.md` is available for change history, although the README does not summarize a upgrade procedure or compatibility matrix. The package is licensed under the MIT License. The license text permits use, copying, modification, merging, publication, distribution, sublicensing, and sale, subject to retaining the copyright and permission notice. That is a project licensing summary, not legal advice. Applications still need to review their own dependencies and obligations. ## Conclusion Adopt it when your React Native app can tolerate delayed, best-effort background work and you need one callback path across iOS and Android. Do not adopt it for precise timers, guaranteed delivery, or iOS work after the app is terminated. Verify the platform behavior first, especially iOS background refresh settings, Android HeadlessJS configuration, and whether your task can finish safely within the available execution window. ## FAQ ### How often does react-native-background-fetch run? The plugin attempts to awaken an app about every 15 minutes, but the README says events can be throttled by the operating system. Delivery may be less frequent depending on usage patterns and platform settings. ### Can react-native-background-fetch run after an iOS app is terminated? No. The README states that iOS no longer fires events when the app is terminated and that there is no iOS equivalent of `stopOnTerminate: false`. ### What is the difference between Android HeadlessJS and iOS background fetch? The Android implementation can continue handling events after app termination when `enableHeadless` is configured. On iOS, terminated apps do not receive events, and background refresh can also be disabled by the user. ## Sources - [Issues](https://github.com/transistorsoft/react-native-background-fetch/issues) - [License: MIT](https://github.com/transistorsoft/react-native-background-fetch/blob/master/LICENSE) - [README](https://github.com/transistorsoft/react-native-background-fetch/blob/master/README.md) - [transistorsoft/react-native-background-fetch on GitHub](https://github.com/transistorsoft/react-native-background-fetch) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/transistorsoft-react-native-background-fetch