In this tutorial, we’ll explore how to implement background tasks in an Ionic app using Capacitor and the @capawesome/capacitor-background-task package. This package simplifies handling background tasks in Capacitor-based applications, allowing you to execute code in the background efficiently.


Before starting, ensure you have the following installed:

  • Node.js and npm
  • Ionic CLI
  • Capacitor CLI

Step 1: Create a New Ionic App

First, let’s create a new Ionic app using the Ionic CLI:

ionic start background-task-example blank --type=angular
cd background-task-example

Step 2: Install the Capacitor and @capawesome/capacitor-background-task

Install the Capacitor and the @capawesome/capacitor-background-task package in your Ionic project:
npm install @capacitor/core @capacitor/cli @capawesome/capacitor-background-task

Step 3: Initialize the Capacitor and Add Platforms

Initialize the Capacitor in your project and add the desired platforms:

npx cap init
npx cap add android
npx cap add ios

Step 4: Implement Background Task Logic

Create a TypeScript file to contain the logic for your background task. Let’s call it background-task.service.ts. This file will handle the background task logic, such as fetching data from an API.

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

const { Http } = Plugins;

export class BackgroundTaskService {
  async fetchDataInBackground() {
    try {
      const result = await Http.request({
        method: 'GET',
        url: '',

      console.log('Background Task Result:',;
    } catch (error) {
      console.error('Error fetching data:', error);
    } finally {
      await BackgroundTask.finish();

In this example, fetchDataInBackground() fetches data from an API endpoint and logs the result. After the task is completed, it calls BackgroundTask.finish() to indicate that the background task has finished executing.

Step 5: Register Background Task

Register the background task in your Ionic app’s codebase. Open src/app/app.component.ts Add the following code to register the background task:

import { Component, OnInit } from '@angular/core';
import { BackgroundTaskService } from './background-task.service';
import { Plugins } from '@capacitor/core';

const { App, BackgroundTask } = Plugins;

  selector: 'app-root',
  templateUrl: 'app.component.html',
  styleUrls: ['app.component.scss'],
export class AppComponent implements OnInit {
  constructor(private backgroundTaskService: BackgroundTaskService) {}

  ngOnInit() {
    App.addListener('appStateChange', async (state) => {
      if (!state.isActive) {
        // App is in the background
        const taskId = await BackgroundTask.beforeExit(async () => {
          // Execute background task
          await this.backgroundTaskService.fetchDataInBackground();
        // Ensure the background task finishes within a reasonable time
        setTimeout(() => {
          BackgroundTask.finish({ taskId });
        }, 3000);

In this code:

  • We listen for changes in the app’s state using App.addListener('appStateChange').
  • When the app goes into the background (!state.isActive), we register a background task using BackgroundTask.beforeExit().
  • Inside the background task, we execute the fetchDataInBackground() method from our BackgroundTaskService.
  • We ensure that the background task finishes within a reasonable time using setTimeout() and BackgroundTask.finish().

Step 6: Test the App

Now, build your Ionic app and deploy it to a device or emulator:

ionic build
npx cap sync
npx cap open android  # or ios

Test the app by running it on a device or emulator. Put the app in the background, and you should see the background task fetching data from the API and logging the result.

That’s it! You’ve successfully implemented background tasks in your Ionic app using Capacitor and the @capawesome/capacitor-background-task package.


Background tasks are essential for maintaining app functionality and providing a seamless user experience. With the Capacitor and the @capawesome/capacitor-background-task package, implementing background tasks in Ionic apps becomes straightforward, allowing you to leverage native device capabilities efficiently.

Experiment with different use cases and explore the Capacitor’s capabilities to unlock the full potential of background tasks in your Ionic apps.

Read More Blog

Quick Game