JavaScript Background Sync API

Imagine a user submits a form while their internet connection suddenly disappears. Normally, the request fails and the user has to try again.

The Background Sync API helps solve this problem by allowing a web application to postpone certain network requests until the device has a connection again.

Learn software development

What Is Background Sync?

Background Sync is a browser API that works with Service Workers.

Instead of sending a request immediately and failing when the network is unavailable, your application can register a sync task. The browser can then retry that task when connectivity returns.

The basic flow is:

User action → Service Worker → Request queued → Internet returns → Request processed

This is particularly useful for Progressive Web Apps (PWAs).

How It Works

First, your application needs a Service Worker.

navigator.serviceWorker.ready.then(async (registration) => {
  await registration.sync.register("send-message");
});

Here, "send-message" is a tag identifying the background synchronization task.

The Service Worker listens for the sync event:

self.addEventListener("sync", (event) => {
  if (event.tag === "send-message") {
    event.waitUntil(sendMessage());
  }
});

You can then perform the network operation:

async function sendMessage() {
  const response = await fetch("/api/messages", {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      message: "Hello from the background!"
    })
  });

  if (!response.ok) {
    throw new Error("Failed to send message");
  }
}

Why Use Background Sync?

1. Handle unreliable connections

Users can continue interacting with your application even when their connection temporarily disappears.

2. Improve user experience

Instead of displaying an immediate network error, your application can attempt the operation later.

3. Useful for PWAs

Background Sync is especially valuable for applications designed to work in unreliable or intermittent network environments.

4. Reduce failed requests

Operations can be retried when the browser determines that network connectivity is available.

Background Sync vs Normal Fetch

With a normal request:

User action
    ↓
fetch()
    ↓
Network unavailable
    ↓
Request fails

With Background Sync:

User action
    ↓
Store request/data
    ↓
Register sync
    ↓
Network unavailable
    ↓
Browser waits
    ↓
Connection returns
    ↓
Service Worker runs
    ↓
Request is sent

Important: Store Data for Later

Background Sync does not magically remember arbitrary requests.

If you need to retry data later, you typically store the relevant information locally, commonly using IndexedDB.

For example:

const requestData = {
  name: "John",
  message: "Hello"
};

// Store requestData in IndexedDB
// Register a background sync task

The Service Worker can retrieve the stored data when synchronization occurs.

One-Time Background Sync

The example above uses one-time Background Sync.

registration.sync.register("upload-data");

The browser attempts to trigger the corresponding sync event when appropriate.

This is different from continuously running background jobs.

Periodic Background Sync

There is also Periodic Background Sync, which is designed for periodically updating application content.

Conceptually:

Every so often
      ↓
Browser wakes Service Worker
      ↓
Fetch updated content
      ↓
Store/update cached data

However, periodic background execution has additional browser and permission constraints and should not be treated as a guaranteed timer.

Things to Keep in Mind

Background Sync has several limitations:

• Browser support is not universal.
• Service Workers must be available.
• The browser controls when synchronization occurs.
• Sync is not guaranteed to happen immediately.
• Long-running background tasks are not appropriate.
• Important data should be persisted reliably before registering the sync.
• Your server should safely handle duplicate requests because retries can potentially result in the same operation being submitted more than once.

A Practical Example

Consider an offline note-taking PWA.

A user writes:

Meeting starts at 10:00 AM.

They press Save, but their connection is unavailable.

Your application can:

1. Save the note locally.
2. Register a background sync.
3. Tell the user the note is waiting to be synchronized.
4. Let the Service Worker attempt the upload later.
5. Mark the note as synchronized after the server confirms it.

This creates a much more resilient offline experience.

The Key Idea

The Background Sync API isn’t about making the internet work offline.

It’s about allowing your application to delay network-dependent work until a better opportunity to perform it becomes available.

For developers building PWAs and offline-first applications, it can be a powerful part of a broader architecture involving:

Service Workers + IndexedDB + Cache API + Background Sync

That combination can turn a web application from something that simply fails when the network disappears into an application that can gracefully handle unreliable connectivity.