React Offline Sync - Interactive Documentation

Enterprise-grade offline
synchronization for React.

Building offline-first apps is hard. This library handles the complexity of queueing mutations to IndexedDB, managing auto-sync, and handling smart retries so you don't have to.

TypeScript Ready IndexedDB Exponential Backoff MIT License

Architecture Simulator

Experience how the library manages data flow. Toggle the Network Status to see how requests are handled differently when Online vs. Offline. Watch the Queue populate when offline and flush when connection restores.

Control Panel

⚛️ React App useOfflineMutation

⚙️ Sync Engine

Queue Empty

IndexedDB

☁️ API Server REST Endpoint

Status: 200 OK

> System initialized. Ready.

Smart Retries Logic

When the server returns a 5xx error, the engine doesn't spam the API. It uses Exponential Backoff to increase the delay between attempts, capped at 30 seconds.

Why IndexedDB?

Unlike localStorage (which is blocking and limited to ~5MB), this library uses IndexedDB. This ensures your main thread stays responsive even with large queues.

🧠

No Blocking

Runs independently of React render cycle.

🔄

Auto-Sync

Listens to window.onLine events automatically.

🛡️

Type-Safe

Full TypeScript definitions included.

🔐

Auth Ready

Inject fresh tokens before sync.

Integration Guide

Implementation is a two-step process: Wrap your app with the Provider, then use the Hook. Toggle the tabs below to see the code.

// App.tsx
import React from 'react';
import { OfflineSyncProvider } from '@imirfanul/react-offline-sync';
import MyComponent from './MyComponent';

const App = () => {
  return (
    // Wraps the entire application context
    <OfflineSyncProvider>
      <MyComponent />
    </OfflineSyncProvider>
  );
};

export default App;

// MyComponent.tsx
import React, { useState } from 'react';
import { useOfflineMutation, useSyncStatus } from '@imirfanul/react-offline-sync';

const MyComponent = () => {
  const [task, setTask] = useState('');
  const { submit } = useOfflineMutation();
  const { isOnline, isSyncing } = useSyncStatus();

  const handleSave = async () => {
    // Executes immediately if online, queues if offline
    await submit(
      { title: task }, // Body
      { url: '/api/todos', method: 'POST' } // Options
    );
    setTask('');
    alert(isOnline ? 'Saved!' : 'Saved to offline queue!');
  };

  return (
    <div>
      <button onClick={handleSave}>Add Task</button>
      {isSyncing && <span>Syncing...</span>}
    </div>
  );
};

// Dynamic Token Injection
const getFreshToken = async () => {
  const token = localStorage.getItem('access_token');
  return { 
    'Authorization': `Bearer ${token}` 
  };
};

<OfflineSyncProvider 
  prepareHeaders={getFreshToken}
  onSuccess={(res, req) => console.log('Synced:', req.url)}
  onError={(err, req) => console.error('Failed:', req.url)}
  debug={true}
>
  <App />
</OfflineSyncProvider>

API Reference

Detailed breakdown of props and return values.

<OfflineSyncProvider />

prepareHeaders Async Function

Injects headers (like Auth tokens) just before the request executes.
onSuccess Callback

Fired when a queued request successfully syncs with the server.
onError Callback

Fired on permanent failure (e.g., 400 Bad Request).

useOfflineMutation()

Returns a submit function.

submit(body: any, options: MutationOptions)

body: JSON payload
options.url: Endpoint URL
options.method: POST | PUT | PATCH | DELETE

useSyncStatus()

isOnline

boolean

isSyncing