Chrome Background Sync

In this tutorial, you'll learn about Chrome Background Sync. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

Hook

Your PWA or website uses the Background Sync API to queue data when offline and sync when the connection returns. You test it: go offline, submit data, come back online. The sync event never fires. Data stays queued indefinitely.

The Wrong Way

Registering multiple sync events for the same tag overwrites the previous registration. Only the last sync tag remains registered.

// BAD: Registering multiple syncs
navigator.serviceWorker.ready.then(reg => {
    reg.sync.register('sync-data');
    reg.sync.register('sync-data');  // Overwrites the first!
    reg.sync.register('sync-data');  // Still only one registration
});

Sync registered: 'sync-data' (1 registration)
Only last registration is active — duplicates silently ignored

Each sync tag can only be registered once.

The Right Way

Check the service worker status and use the correct sync event registration.

# 1. Check service worker is installed
# chrome://serviceworker-internals/ → Find your site

# 2. Verify the service worker intercepts correctly
# chrome://inspect/#service-workers → Click "Inspect" on your SW

// 3. Check the sync event listener in the service worker
self.addEventListener('sync', event => {
    if (event.tag === 'sync-data') {
        event.waitUntil(
            syncData().catch(err => {
                console.error('Sync failed:', err);
                // If you don't re-register, the sync is not retried
                return event.tag;
            })
        );
    }
});

# 4. Check if the sync event is being blocked
# Chrome's Background Sync is restricted to HTTPS
# The sync event fires only when:
# - The device has network connectivity
# - The browser is running (not fully quit)
# - The sync event is registered with a non-empty tag

# 5. Test with Chrome DevTools
# Application → Service Workers → "Update" → "Sync"
# Click "Sync" for a specific tag to trigger it manually

# 6. Check if the sync fired but failed
# chrome://serviceworker-internals/ → Click "Start" → Check console

Sync event 'sync-data' fired
Data synced successfully ✓

If sync still does not fire, check if the registration is timing out:

// Increase sync timeout (default: 30 seconds)
self.addEventListener('sync', event => {
    event.waitUntil(
        // Timeout after 2 minutes
        Promise.race([
            syncData(),
            new Promise((_, reject) => setTimeout(() => reject('timeout'), 120000))
        ])
    );
});

Prevention

• Register each sync tag only once.
• Wait for the previous sync to complete before re-registering.
• Keep the service worker alive — Chrome may kill idle workers after 30 seconds.
• Use periodicSync for regular background sync (Chrome 80+).
• Test with DevTools manual sync trigger before relying on automatic firing.

Common Mistakes with background sync

1. Using head and tail instead of pattern matching, causing runtime errors on empty lists
2. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
3. Using return to exit a function early instead of wrapping a pure value in the monad

These mistakes appear frequently in real-world CHROME code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

DodaTech — sync that works even when you are offline.