React Native Offline Sync Engine

A production-ready offline-first sync engine for React Native that works as middleware with Axios.

Instead of replacing your API client, this library enhances it by automatically queuing failed requests (due to no internet) and retrying them when connectivity is restored.

🚀 Features

• 📦 Automatic offline request queueing
• 🔄 Auto retry when internet is back
• ⚡ Axios interceptor support (no API change required)
• 🌐 Network detection
• 🧩 Pluggable storage (AsyncStorage, SQLite, MMKV)
• 🧠 Retry & failure handling
• 🪶 Lightweight and scalable

📦 Installation

npm install react-native-offline-sync

Install peer dependencies:

npm install axios @react-native-async-storage/async-storage @react-native-community/netinfo

🧠 How It Works

1. Your app makes API calls using Axios
2. If request fails due to no internet → it is automatically stored in queue
3. When internet is restored → queued requests are retried
4. No changes needed in existing API calls

⚙️ Setup

1. Create Axios instance

import axios from 'axios'

const api = axios.create({
  baseURL: 'https://api.example.com'
})

2. Setup Offline Sync Middleware

import {
  QueueManager,
  SyncProcessor,
  asyncStorageAdapter
} from 'react-native-offline-sync'

import { setupOfflineSync } from 'react-native-offline-sync/integrations'

const queueManager = new QueueManager(asyncStorageAdapter)

const syncProcessor = new SyncProcessor(queueManager, {
  baseUrl: 'https://api.example.com'
})

// attach middleware
setupOfflineSync(api, queueManager, syncProcessor)

🔥 Usage (No Change Required)

await api.post('/cart/add', { id: 1 })

👉 If offline → request is automatically queued 👉 If online → request works normally

🔄 Manual Sync (Optional)

await syncProcessor.processQueue()

⚙️ Advanced Configuration

const syncProcessor = new SyncProcessor(queueManager, {
  baseUrl: 'https://api.example.com',
  maxRetries: 3,
  retryDelay: 2000,

  onSuccess: (item, response) => {
    console.log('Synced:', item)
  },

  onError: (item, error) => {
    console.log('Failed:', item)
  }
})

🔧 Custom Request Executor (Axios Integration)

To fully use Axios for retry:

const syncProcessor = new SyncProcessor(queueManager, {
  executeRequest: (item) => {
    return api({
      url: item.endpoint,
      method: item.method,
      data: item.payload,
      headers: item.headers
    })
  }
})

🧩 Storage Adapters

Default:

import { asyncStorageAdapter } from 'react-native-offline-sync'

Custom adapter support:

export interface StorageAdapter {
  setItem(key: string, value: string): Promise<void>
  getItem(key: string): Promise<string | null>
  removeItem(key: string): Promise<void>
}

📁 Queue Structure

{
  "id": "unique_id",
  "endpoint": "/api/path",
  "method": "POST",
  "payload": {},
  "status": "pending",
  "retries": 0,
  "timestamp": 1710000000
}

🛠️ Future Roadmap

• Conflict resolution
• Optimistic UI updates
• Background sync
• Batch processing
• Redux integration

🤝 Contributing

Pull requests and contributions are welcome.

📄 License

MIT License

👨‍💻 Author

Monesh Tilavi