@capgo/capacitor-background-task

Get instant updates for your app with Capgo

Need a plugin feature? We can build it

Periodic background task scheduling for Capacitor apps. It follows the practical feature set of Expo BackgroundTask: named tasks, persistent registration, status checks, unregistering, a testing trigger, and iOS expiration events.

What It Does

• Schedules periodic background work on Android with WorkManager.
• Schedules background processing on iOS with BGTaskScheduler.
• Supports multiple named tasks with minimumInterval in minutes.
• Emits retained task events so task runs recorded before JavaScript is ready can be drained.
• Provides a small react-native-background-task compatible API: define, schedule, cancel, statusAsync, and finish.

Limits

• Background tasks are not exact timers. Android and iOS decide when work actually runs.
• Android enforces a 15 minute minimum interval.
• iOS may delay runs substantially based on battery, network, and user behavior.
• iOS background tasks do not run in the simulator; use a physical device.
• This plugin cannot make an app run indefinitely in the background.

Compatibility

Plugin version	Capacitor compatibility	Maintained
v8.*.*	v8.*.*	✅
v7.*.*	v7.*.*	On demand
v6.*.*	v6.*.*	On demand

Policy:

• New plugins start at version 8.0.0 (Capacitor 8 baseline).
• Backward compatibility for older Capacitor majors is supported on demand.

Install

npm install @capgo/capacitor-background-task
npx cap sync

iOS Setup

Add the background processing mode and permitted task identifier to ios/App/App/Info.plist:

<key>UIBackgroundModes</key>
<array>
  <string>processing</string>
</array>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>app.capgo.backgroundtask.processing</string>
</array>

Usage

Define tasks at module scope so they are available as soon as the app is started by the OS.

import { BackgroundTask, BackgroundTaskResult } from '@capgo/capacitor-background-task';

const SYNC_TASK = 'sync-offline-data';

BackgroundTask.defineTask(SYNC_TASK, async () => {
  try {
    await fetch('https://example.com/sync', { method: 'POST' });
    return BackgroundTaskResult.Success;
  } catch {
    return BackgroundTaskResult.Failed;
  }
});

await BackgroundTask.registerTaskAsync(SYNC_TASK, {
  minimumInterval: 30,
  requiresNetwork: true,
});

Testing

await BackgroundTask.triggerTaskWorkerForTestingAsync();

React Native Compatibility

import { BackgroundTask } from '@capgo/capacitor-background-task';

BackgroundTask.define(async () => {
  await fetch('https://example.com/sync', { method: 'POST' });
});

await BackgroundTask.schedule({
  period: 1800,
});

Example App

The example-app/ folder is linked via file:.. and is intended for validating native wiring during development.

API

• defineTask(...)
• registerTaskAsync(...)
• unregisterTaskAsync(...)
• isTaskRegisteredAsync(...)
• getRegisteredTasksAsync()
• getPendingTaskRunsAsync()
• getStatusAsync()
• triggerTaskWorkerForTestingAsync()
• addExpirationListener(...)
• define(...)
• schedule(...)
• cancel()
• statusAsync()
• finish(...)
• Interfaces
• Type Aliases
• Enums

defineTask(...)

defineTask(taskName: string, callback: BackgroundTaskCallback) => void

Define the JavaScript callback for a task. Call this at module/global scope.

Param	Type
taskName	string
callback	BackgroundTaskCallback

---

registerTaskAsync(...)

registerTaskAsync(taskName: string, options?: BackgroundTaskOptions | undefined) => Promise<void>

Register a named periodic background task.

Param	Type
taskName	string
options	BackgroundTaskOptions

---

unregisterTaskAsync(...)

unregisterTaskAsync(taskName: string) => Promise<void>

Unregister a named periodic background task.

Param	Type
taskName	string

---

isTaskRegisteredAsync(...)

isTaskRegisteredAsync(taskName: string) => Promise<boolean>

Check whether a named task is registered.

Param	Type
taskName	string

Returns: Promise<boolean>

---

getRegisteredTasksAsync()

getRegisteredTasksAsync() => Promise<string[]>

Return all registered task names.

Returns: Promise<string[]>

---

getPendingTaskRunsAsync()

getPendingTaskRunsAsync() => Promise<BackgroundTaskEvent[]>

Return pending task runs that native recorded before JavaScript was ready.

Returns: Promise<BackgroundTaskEvent[]>

---

getStatusAsync()

getStatusAsync() => Promise<BackgroundTaskStatus>

Return native background task availability.

Returns: Promise<BackgroundTaskStatus>

---

triggerTaskWorkerForTestingAsync()

triggerTaskWorkerForTestingAsync() => Promise<boolean>

Trigger all registered tasks immediately for development/testing.

Returns: Promise<boolean>

---

addExpirationListener(...)

addExpirationListener(listener: (event: BackgroundTaskEvent) => void) => Promise<PluginListenerHandle>

Listen for iOS expiration callbacks.

Param	Type
listener	(event: BackgroundTaskEvent) => void

Returns: Promise<PluginListenerHandle>

---

define(...)

define(callback: BackgroundTaskCallback) => void

React Native background-task compatible single-task define helper.

Param	Type
callback	BackgroundTaskCallback

---

schedule(...)

schedule(options?: ReactNativeBackgroundTaskOptions | undefined) => Promise<void>

React Native background-task compatible single-task scheduler.

Param	Type
options	ReactNativeBackgroundTaskOptions

---

cancel()

cancel() => Promise<void>

React Native background-task compatible single-task cancel helper.

---

statusAsync()

statusAsync() => Promise<ReactNativeBackgroundTaskStatus>

React Native background-task compatible status helper.

Returns: Promise<ReactNativeBackgroundTaskStatus>

---

finish(...)

finish(result?: BackgroundTaskResult | undefined) => Promise<void>

React Native background-task compatible finish helper. Normal Expo-style callbacks are finished automatically.

Param	Type
result	BackgroundTaskResult

---

Interfaces

BackgroundTaskEvent

Payload emitted when native scheduling asks JavaScript to run a task.

Prop	Type	Description
taskName	string	Name passed to registerTaskAsync.
taskId	string	Native run identifier. The JavaScript wrapper finishes it automatically when the defined callback resolves.
timestamp	number	Native timestamp for the run.
test	boolean	True when triggered through triggerTaskWorkerForTestingAsync.

BackgroundTaskOptions

Options for registering a periodic background task.

Prop	Type	Description
minimumInterval	number	Inexact interval in minutes between task runs. Defaults to 720 minutes. Android enforces a 15 minute minimum. iOS treats this as an earliest begin date and may run much later.
requiresNetwork	boolean	Require an active network before running the native scheduler. Defaults to true.

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

ReactNativeBackgroundTaskOptions

React Native background-task compatible schedule options.

Prop	Type	Description
period	number	Desired seconds between each execution. Mapped to minimumInterval minutes.
timeout	number	Android-only timeout hint kept for API compatibility.

ReactNativeBackgroundTaskStatus

React Native background-task compatible status payload.

Prop	Type	Description
available	boolean	Whether background tasks are available to the app.
unavailableReason	string	Reason when unavailable.

Type Aliases

BackgroundTaskCallback

Function executed for a background task.

(event: BackgroundTaskEvent): void | BackgroundTaskResult | Promise<void | BackgroundTaskResult>

Enums

BackgroundTaskResult

Members	Value	Description
Success	1	The task finished successfully.
Failed	2	The task failed.

BackgroundTaskStatus

Members	Value	Description
Restricted	1	Background task scheduling is unavailable or restricted.
Available	2	Background task scheduling is available.