@capgo/capacitor-background-task

Run periodic background tasks in your Capacitor app on iOS and Android, with named tasks that survive app restarts. Sync data or refresh content while the app is not open.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-background-task in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-background-task to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Named tasks: registerTaskAsync() and unregisterTaskAsync() with options like minimumInterval and requiresNetwork.
• Status: isTaskRegisteredAsync(), getRegisteredTasksAsync() and getStatusAsync() report what is scheduled and available.
• Missed runs: getPendingTaskRunsAsync() returns runs recorded natively before JavaScript was ready.
• Testing: triggerTaskWorkerForTestingAsync() runs all registered tasks right away during development.
• Familiar API: an Expo BackgroundTask style API plus React Native background-task compatible schedule(), cancel() and finish().
• Platforms: iOS and Android. iOS uses BackgroundTasks, Android uses WorkManager. Web is a stub.

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

Policy:

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

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-background-task` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

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.

registerTaskAsync(...)

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

Register a named periodic background task.

unregisterTaskAsync(...)

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

Unregister a named periodic background task.

isTaskRegisteredAsync(...)

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

Check whether a named task is registered.

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.

Returns: Promise<PluginListenerHandle>

define(...)

define(callback: BackgroundTaskCallback) => void

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

schedule(...)

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

React Native background-task compatible single-task scheduler.

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.

Interfaces

BackgroundTaskEvent

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

BackgroundTaskOptions

Options for registering a periodic background task.

PluginListenerHandle

ReactNativeBackgroundTaskOptions

React Native background-task compatible schedule options.

ReactNativeBackgroundTaskStatus

React Native background-task compatible status payload.

Type Aliases

BackgroundTaskCallback

Function executed for a background task.

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

Enums

BackgroundTaskResult

BackgroundTaskStatus