What is workbox-background-sync?
The workbox-background-sync npm package is part of the Workbox suite of service worker libraries, designed to make offline caching, background sync, and other service worker features easier to implement. It provides a way to reliably sync data with a web server even when a user's device is offline. The package queues failed requests and retries them when the network is available again.
What are workbox-background-sync's main functionalities?
Queueing failed requests
This feature allows developers to queue failed POST requests when the network is unavailable. The requests are retried automatically when the network comes back online. The code sample shows how to register a route that captures failed POST requests to URLs ending with 'json' and uses the background sync plugin to manage the queue.
workbox.routing.registerRoute(
new RegExp('/api/.*\json'),
new workbox.strategies.NetworkOnly({
plugins: [
new workbox.backgroundSync.Plugin('myQueueName', {
maxRetentionTime: 24 * 60 // Retry for max of 24 Hours
})
]
}),
'POST'
);
Customizing the retry mechanism
This feature allows developers to customize the behavior of the background sync process. The code sample demonstrates how to add a callback function that is called when the sync event occurs. Developers can use this to add custom logic for handling the retry of queued requests.
const bgSyncPlugin = new workbox.backgroundSync.Plugin('myQueueName', {
maxRetentionTime: 24 * 60, // Retry for max of 24 Hours
onSync: async ({ queue }) => {
let entry;
while (entry = await queue.shiftRequest()) {
try {
await fetch(entry.request);
console.log('Replay successful for request', entry.request);
} catch (error) {
console.error('Replay failed for request', entry.request, error);
// Put the entry back in the queue and rethrow the error:
await queue.unshiftRequest(entry);
throw error;
}
}
console.log('Replay complete!');
}
});
Other packages similar to workbox-background-sync
offline-plugin
The 'offline-plugin' is a webpack plugin designed to provide offline experience for webpack projects. It includes features like service worker generation and asset caching but does not focus specifically on background sync like workbox-background-sync. It is more of a general offline solution.
workbox-background-sync
Queues failed requests and uses the Background Sync API to replay those requests at a later time when the network state has changed.
Installation
npm install --save-dev workbox-background-sync
Demo
Browse sample source code in the demo directory.
Reference Docs
You can find documentation for this module here.