Offline Request Queuing and Sync with Axios

Offline request queuing allows web applications to intercept outgoing HTTP requests when a user lacks network connectivity, store them securely on the client, and automatically synchronize them with the server once the connection is restored. When using the Axios HTTP client, achieving this offline-first architecture requires a combination of network status detection, Axios interceptors, persistent client-side storage, and automated replay mechanisms.

1. Network Detection and Axios Interceptors

The foundation of offline handling is detecting network state changes and intercepting outgoing traffic. You can monitor connectivity via the browser's navigator.onLine API alongside online and offline event listeners.

By applying Axios request interceptors, the application can evaluate the connection status before an HTTP call leaves the client:

  • Online: The request proceeds normally.
  • Offline: The interceptor cancels or pauses the actual HTTP dispatch, serializes the request configuration (URL, HTTP method, headers, query parameters, and payload data), and diverts it to a local storage queue.

Alternatively, response interceptors can catch network errors (such as ERR_INTERNET_DISCONNECTED or timeout errors) and push the failed request into the queue retroactively.

2. Persistent Client-Side Storage

In-memory queues fail if the user refreshes or closes the browser tab. Reliable offline systems use persistent browser storage to retain pending mutations:

  • IndexedDB: The recommended approach for storing queued requests. It supports structured data, binary blobs, and large storage quotas. Libraries like idb or localforage simplify interaction with IndexedDB.
  • LocalStorage: Suitable only for simple, lightweight requests due to synchronous execution and strict storage limits (typically 5MB).

Each serialized request entry in the database should include a unique identifier, a timestamp, and a status flag (e.g., pending, syncing, failed).

3. Replay and Synchronization Engine

When the online event fires, the application triggers a synchronization manager to process the queue:

  1. Sequential Execution: Requests are read from storage in the order they were created (FIFO) to preserve state consistency.
  2. Re-dispatching: The synchronization engine recreates the Axios request using the stored configuration.
  3. Queue Eviction: Once a request returns a 2xx success status, it is removed from the storage queue.
  4. Retry Strategies: If a request fails due to server-side errors, backoff logic (such as exponential backoff) prevents overwhelming the backend.

4. Service Workers and Workbox Background Sync

For progressive web applications (PWAs), the standard Web Background Sync API enables request synchronization even after the user navigates away from the application.

Using Workbox Background Sync alongside Axios:

  • The Service Worker intercepts network fetches originating from Axios.
  • If the network fails, Workbox stores the request in an IndexedDB queue.
  • The browser replays the request in the background as soon as connectivity returns, even if the application tab has been closed.

5. Idempotency and Conflict Management

Queuing state-changing requests (such as POST, PUT, or DELETE) introduces the risk of duplicate operations or outdated state overrides. Robust implementations utilize:

  • Idempotency Keys: Attaching a unique UUID header (e.g., X-Idempotency-Key) to every queued request ensures that the backend processes duplicate submissions only once.
  • Optimistic UI Updates: Updating the local client state immediately upon user action, then rolling back or notifying the user if the eventual background sync fails permanently.