Skip to main content
Capgo logo
Back to plugins
@capgo/capacitor-background-task
Tutorial
by github.com/Cap-go

Background Task

Schedule periodic background fetch tasks on iOS and Android with Expo-style task registration

Downloads/week

100

GitHub Stars

1

Guide

Tutorial on Background Task

Using @capgo/capacitor-background-task

Schedule periodic background fetch work in a Capacitor app with named tasks, persistent registration, status checks, unregistering, and a development trigger. The plugin uses Android WorkManager and iOS BGTaskScheduler.

Install

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

iOS Setup

Add background processing support 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>

Then run:

npx cap sync ios

What This Plugin Exposes

  • defineTask - Define the JavaScript callback for a named task.
  • registerTaskAsync - Persist and schedule a periodic task.
  • unregisterTaskAsync - Cancel one task.
  • isTaskRegisteredAsync - Check one task's registration state.
  • getRegisteredTasksAsync - List registered task names.
  • getStatusAsync - Check native background task availability.
  • triggerTaskWorkerForTestingAsync - Trigger registered tasks immediately for development.
  • addExpirationListener - React when iOS expires a task.

Example Usage

Define the task at module scope so it is available when the OS wakes the app:

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

const SYNC_TASK = 'sync-offline-data';

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

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

Check status and registered task names:

const status = await BackgroundTask.getStatusAsync();
const tasks = await BackgroundTask.getRegisteredTasksAsync();

console.log({ status, tasks });

Trigger a development run:

await BackgroundTask.triggerTaskWorkerForTestingAsync();

Cancel the task:

await BackgroundTask.unregisterTaskAsync(SYNC_TASK);

Platform Notes

  • Background task schedules are opportunistic, not exact timers.
  • Android periodic work has a 15 minute minimum interval.
  • iOS treats minimumInterval as an earliest begin date and may run later.
  • Test iOS background processing on a physical device.

Full Reference

Keep going from Using @capgo/capacitor-background-task

If you are using Using @capgo/capacitor-background-task to plan native plugin work, connect it with @capgo/capacitor-background-task for the implementation detail in @capgo/capacitor-background-task, Getting Started for the implementation detail in Getting Started, Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, and Adding or Updating Plugins for the implementation detail in Adding or Updating Plugins.