Offline Support

Building mobile applications that work seamlessly without internet connectivity.

Overview

Offline support is essential for mobile applications to provide a reliable user experience regardless of network conditions. This guide covers strategies for implementing offline functionality, data synchronization, and graceful degradation when connectivity is lost.

Why Offline Support Matters

Reliability: Apps work anywhere, anytime
Performance: Faster load times using cached data
User Experience: No frustrating "No Internet" screens
Data Integrity: Queue operations and sync when online
Cost Efficiency: Reduce data usage and server load

Offline Strategies

1. Cache-First Strategy

Load from cache first, then update from network.

const fetchData = async (url) => {
  // Try cache first
  const cached = await getCachedData(url);
  if (cached) {
    return cached;
  }

  // Fetch from network if not cached
  try {
    const response = await fetch(url);
    const data = await response.json();

    // Cache the response
    await cacheData(url, data);

    return data;
  } catch (error) {
    throw new Error('Unable to fetch data');
  }
};

2. Network-First Strategy

Try network first, fall back to cache.

const fetchData = async (url) => {
  try {
    const response = await fetch(url);
    const data = await response.json();

    // Update cache
    await cacheData(url, data);

    return data;
  } catch (error) {
    // Network failed, try cache
    const cached = await getCachedData(url);
    if (cached) {
      return cached;
    }

    throw new Error('No data available');
  }
};

3. Offline-First Strategy

Always work with local data, sync in background.

const saveData = async (data) => {
  // Save locally first
  await saveToLocalStorage(data);

  // Try to sync with server
  if (navigator.onLine) {
    try {
      await syncWithServer(data);
    } catch (error) {
      // Queue for later sync
      await queueForSync(data);
    }
  } else {
    // Queue for sync when online
    await queueForSync(data);
  }
};

Detecting Network Status

Using Network API

import { Network } from '@capacitor/network';

const NetworkStatus = () => {
  const [isOnline, setIsOnline] = useState(true);
  const [connectionType, setConnectionType] = useState('unknown');

  useEffect(() => {
    // Get initial status
    const checkStatus = async () => {
      const status = await Network.getStatus();
      setIsOnline(status.connected);
      setConnectionType(status.connectionType);
    };

    checkStatus();

    // Listen for changes
    const listener = Network.addListener('networkStatusChange', (status) => {
      setIsOnline(status.connected);
      setConnectionType(status.connectionType);

      if (status.connected) {
        handleBackOnline();
      } else {
        handleOffline();
      }
    });

    return () => {
      listener.remove();
    };
  }, []);

  return (
    <div>
      <div className={`status-badge ${isOnline ? 'online' : 'offline'}`}>
        {isOnline ? '🟢 Online' : '🔴 Offline'}
      </div>
      {isOnline && <p>Connection: {connectionType}</p>}
    </div>
  );
};

Using Browser API

const useOnlineStatus = () => {
  const [isOnline, setIsOnline] = useState(navigator.onLine);

  useEffect(() => {
    const handleOnline = () => setIsOnline(true);
    const handleOffline = () => setIsOnline(false);

    window.addEventListener('online', handleOnline);
    window.addEventListener('offline', handleOffline);

    return () => {
      window.removeEventListener('online', handleOnline);
      window.removeEventListener('offline', handleOffline);
    };
  }, []);

  return isOnline;
};

Local Storage Solutions

LocalStorage

Simple key-value storage for small amounts of data.

// Save data
const saveToLocalStorage = (key, data) => {
  try {
    localStorage.setItem(key, JSON.stringify(data));
  } catch (error) {
    console.error('Failed to save to localStorage:', error);
  }
};

// Load data
const loadFromLocalStorage = (key) => {
  try {
    const item = localStorage.getItem(key);
    return item ? JSON.parse(item) : null;
  } catch (error) {
    console.error('Failed to load from localStorage:', error);
    return null;
  }
};

// Remove data
const removeFromLocalStorage = (key) => {
  localStorage.removeItem(key);
};

// Clear all
const clearLocalStorage = () => {
  localStorage.clear();
};

IndexedDB

Structured database for larger datasets.

// Initialize database
const openDatabase = () => {
  return new Promise((resolve, reject) => {
    const request = indexedDB.open('MyAppDB', 1);

    request.onerror = () => reject(request.error);
    request.onsuccess = () => resolve(request.result);

    request.onupgradeneeded = (event) => {
      const db = event.target.result;

      // Create object stores
      if (!db.objectStoreNames.contains('items')) {
        const objectStore = db.createObjectStore('items', { keyPath: 'id' });
        objectStore.createIndex('timestamp', 'timestamp', { unique: false });
      }

      if (!db.objectStoreNames.contains('syncQueue')) {
        db.createObjectStore('syncQueue', { autoIncrement: true });
      }
    };
  });
};

// Save to IndexedDB
const saveToIndexedDB = async (storeName, data) => {
  const db = await openDatabase();
  return new Promise((resolve, reject) => {
    const transaction = db.transaction([storeName], 'readwrite');
    const store = transaction.objectStore(storeName);
    const request = store.put(data);

    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
};

// Load from IndexedDB
const loadFromIndexedDB = async (storeName, key) => {
  const db = await openDatabase();
  return new Promise((resolve, reject) => {
    const transaction = db.transaction([storeName], 'readonly');
    const store = transaction.objectStore(storeName);
    const request = store.get(key);

    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
};

// Load all from IndexedDB
const loadAllFromIndexedDB = async (storeName) => {
  const db = await openDatabase();
  return new Promise((resolve, reject) => {
    const transaction = db.transaction([storeName], 'readonly');
    const store = transaction.objectStore(storeName);
    const request = store.getAll();

    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
};

// Delete from IndexedDB
const deleteFromIndexedDB = async (storeName, key) => {
  const db = await openDatabase();
  return new Promise((resolve, reject) => {
    const transaction = db.transaction([storeName], 'readwrite');
    const store = transaction.objectStore(storeName);
    const request = store.delete(key);

    request.onsuccess = () => resolve();
    request.onerror = () => reject(request.error);
  });
};

Capacitor Storage

Cross-platform key-value storage.

import { Storage } from '@capacitor/storage';

// Save data
const saveToStorage = async (key, value) => {
  await Storage.set({
    key: key,
    value: JSON.stringify(value),
  });
};

// Load data
const loadFromStorage = async (key) => {
  const { value } = await Storage.get({ key: key });
  return value ? JSON.parse(value) : null;
};

// Remove data
const removeFromStorage = async (key) => {
  await Storage.remove({ key: key });
};

// Clear all
const clearStorage = async () => {
  await Storage.clear();
};

// Get all keys
const getAllKeys = async () => {
  const { keys } = await Storage.keys();
  return keys;
};

Data Synchronization

Sync Queue Implementation

class SyncQueue {
  constructor() {
    this.queueKey = 'syncQueue';
  }

  async add(operation) {
    const queue = await this.getQueue();
    queue.push({
      ...operation,
      id: Date.now(),
      timestamp: new Date().toISOString(),
      retries: 0,
    });
    await this.saveQueue(queue);
  }

  async getQueue() {
    const queue = await loadFromStorage(this.queueKey);
    return queue || [];
  }

  async saveQueue(queue) {
    await saveToStorage(this.queueKey, queue);
  }

  async process() {
    if (!navigator.onLine) {
      console.log('Offline, skipping sync');
      return;
    }

    const queue = await this.getQueue();
    if (queue.length === 0) return;

    console.log(`Processing ${queue.length} queued operations`);

    const remaining = [];

    for (const operation of queue) {
      try {
        await this.executeOperation(operation);
        console.log('Operation synced:', operation.id);
      } catch (error) {
        console.error('Sync failed:', error);

        // Retry logic
        operation.retries++;
        if (operation.retries < 3) {
          remaining.push(operation);
        } else {
          console.error('Max retries reached, dropping operation:', operation);
        }
      }
    }

    await this.saveQueue(remaining);
  }

  async executeOperation(operation) {
    switch (operation.type) {
      case 'CREATE':
        return fetch(operation.url, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(operation.data),
        });

      case 'UPDATE':
        return fetch(operation.url, {
          method: 'PUT',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(operation.data),
        });

      case 'DELETE':
        return fetch(operation.url, {
          method: 'DELETE',
        });

      default:
        throw new Error(`Unknown operation type: ${operation.type}`);
    }
  }

  async clear() {
    await this.saveQueue([]);
  }
}

// Usage
const syncQueue = new SyncQueue();

// Add operation to queue
await syncQueue.add({
  type: 'CREATE',
  url: '/api/items',
  data: { name: 'New Item', description: 'Description' },
});

// Process queue when online
window.addEventListener('online', () => {
  syncQueue.process();
});

Background Sync

Using Service Worker Background Sync API.

// Register background sync
const registerBackgroundSync = async () => {
  if ('serviceWorker' in navigator && 'sync' in navigator.serviceWorker) {
    const registration = await navigator.serviceWorker.ready;
    await registration.sync.register('syncData');
  }
};

// Service Worker (service-worker.js)
self.addEventListener('sync', (event) => {
  if (event.tag === 'syncData') {
    event.waitUntil(syncData());
  }
});

const syncData = async () => {
  // Get queued operations
  const queue = await getQueuedOperations();

  for (const operation of queue) {
    try {
      await fetch(operation.url, {
        method: operation.method,
        headers: operation.headers,
        body: operation.body,
      });

      // Remove from queue after successful sync
      await removeFromQueue(operation.id);
    } catch (error) {
      console.error('Sync failed:', error);
    }
  }
};

Offline Data Management

Caching Strategy with React Hook

const useOfflineData = (url, fetchFunction) => {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  const isOnline = useOnlineStatus();

  useEffect(() => {
    const loadData = async () => {
      setLoading(true);

      // Try to load cached data first
      const cached = await loadFromStorage(url);
      if (cached) {
        setData(cached);
        setLoading(false);
      }

      // If online, fetch fresh data
      if (isOnline) {
        try {
          const fresh = await fetchFunction();
          setData(fresh);
          await saveToStorage(url, fresh);
          setError(null);
        } catch (err) {
          setError(err);
          // If fetch fails but we have cache, use it
          if (!cached) {
            setLoading(false);
          }
        }
      }

      setLoading(false);
    };

    loadData();
  }, [url, isOnline]);

  return { data, loading, error, isOnline };
};

// Usage
const ProductList = () => {
  const { data: products, loading, error, isOnline } = useOfflineData(
    'products',
    () => fetch('/api/products').then(r => r.json())
  );

  return (
    <div>
      {!isOnline && (
        <div className="offline-banner">
          You're offline. Showing cached data.
        </div>
      )}

      {loading && <div>Loading...</div>}
      {error && <div>Error: {error.message}</div>}

      <div className="product-grid">
        {products?.map(product => (
          <ProductCard key={product.id} product={product} />
        ))}
      </div>
    </div>
  );
};

Optimistic Updates

Update UI immediately, sync later.

const useOptimisticUpdate = () => {
  const [items, setItems] = useState([]);
  const syncQueue = new SyncQueue();
  const isOnline = useOnlineStatus();

  const addItem = async (item) => {
    // Optimistic update
    const newItem = { ...item, id: `temp-${Date.now()}`, pending: true };
    setItems([...items, newItem]);

    // Queue for sync
    await syncQueue.add({
      type: 'CREATE',
      url: '/api/items',
      data: item,
      localId: newItem.id,
    });

    // Process immediately if online
    if (isOnline) {
      try {
        const response = await fetch('/api/items', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(item),
        });

        const serverItem = await response.json();

        // Replace temp item with server response
        setItems(items.map(i =>
          i.id === newItem.id ? { ...serverItem, pending: false } : i
        ));
      } catch (error) {
        // Mark as failed but keep in list
        setItems(items.map(i =>
          i.id === newItem.id ? { ...i, pending: false, error: true } : i
        ));
      }
    }
  };

  const deleteItem = async (id) => {
    // Optimistic delete
    setItems(items.filter(i => i.id !== id));

    // Queue for sync
    await syncQueue.add({
      type: 'DELETE',
      url: `/api/items/${id}`,
    });

    // Sync if online
    if (isOnline) {
      try {
        await fetch(`/api/items/${id}`, { method: 'DELETE' });
      } catch (error) {
        // Restore item on error
        const item = items.find(i => i.id === id);
        if (item) {
          setItems([...items, item]);
        }
      }
    }
  };

  return { items, addItem, deleteItem };
};

Service Workers

Basic Service Worker Setup

// Register service worker
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/service-worker.js')
    .then(registration => {
      console.log('Service Worker registered:', registration);
    })
    .catch(error => {
      console.error('Service Worker registration failed:', error);
    });
}

// service-worker.js
const CACHE_NAME = 'my-app-v1';
const urlsToCache = [
  '/',
  '/index.html',
  '/styles.css',
  '/app.js',
  '/offline.html',
];

// Install event - cache assets
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then(cache => cache.addAll(urlsToCache))
  );
});

// Fetch event - serve from cache
self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request)
      .then(response => {
        // Cache hit - return response
        if (response) {
          return response;
        }

        // Clone the request
        const fetchRequest = event.request.clone();

        return fetch(fetchRequest).then(response => {
          // Check if valid response
          if (!response || response.status !== 200 || response.type !== 'basic') {
            return response;
          }

          // Clone the response
          const responseToCache = response.clone();

          caches.open(CACHE_NAME)
            .then(cache => {
              cache.put(event.request, responseToCache);
            });

          return response;
        }).catch(() => {
          // Return offline page for navigation requests
          if (event.request.mode === 'navigate') {
            return caches.match('/offline.html');
          }
        });
      })
  );
});

// Activate event - clean old caches
self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then(cacheNames => {
      return Promise.all(
        cacheNames.map(cacheName => {
          if (cacheName !== CACHE_NAME) {
            return caches.delete(cacheName);
          }
        })
      );
    })
  );
});

Offline UI Patterns

const OfflineBanner = () => {
  const isOnline = useOnlineStatus();

  if (isOnline) return null;

  return (
    <div className="offline-banner">
      <div className="offline-content">
        <span className="offline-icon">📡</span>
        <span>You're offline. Some features may be limited.</span>
      </div>
    </div>
  );
};

Sync Status Indicator

const SyncStatus = () => {
  const [syncQueue, setSyncQueue] = useState([]);
  const [syncing, setSyncing] = useState(false);

  const checkQueue = async () => {
    const queue = await new SyncQueue().getQueue();
    setSyncQueue(queue);
  };

  useEffect(() => {
    checkQueue();
    const interval = setInterval(checkQueue, 5000);
    return () => clearInterval(interval);
  }, []);

  if (syncQueue.length === 0) return null;

  return (
    <div className="sync-status">
      {syncing ? (
        <span>🔄 Syncing...</span>
      ) : (
        <span>📤 {syncQueue.length} pending changes</span>
      )}
    </div>
  );
};

Testing Offline Functionality

// Simulate offline mode in tests
describe('Offline functionality', () => {
  beforeEach(() => {
    // Mock navigator.onLine
    Object.defineProperty(navigator, 'onLine', {
      writable: true,
      value: false,
    });
  });

  test('shows offline banner when offline', () => {
    const { getByText } = render(<App />);
    expect(getByText(/you're offline/i)).toBeInTheDocument();
  });

  test('queues operations when offline', async () => {
    const syncQueue = new SyncQueue();
    await syncQueue.add({ type: 'CREATE', url: '/api/items', data: {} });

    const queue = await syncQueue.getQueue();
    expect(queue.length).toBe(1);
  });
});

Best Practices

1. Cache Intelligently

Cache essential assets and API responses, but not everything.

2. Provide Clear Feedback

Show users when they're offline and what functionality is limited.

3. Queue Operations

Don't lose user data - queue operations for later sync.

4. Handle Conflicts

Implement conflict resolution for simultaneous edits.

5. Expire Old Cache

Remove outdated cached data to prevent stale information.

const isCacheExpired = (timestamp, maxAge = 3600000) => {
  return Date.now() - timestamp > maxAge;
};

Offline Support

Overview

Why Offline Support Matters

Offline Strategies

1. Cache-First Strategy

2. Network-First Strategy

3. Offline-First Strategy

Detecting Network Status

Using Network API

Using Browser API

Local Storage Solutions

LocalStorage

IndexedDB

Capacitor Storage

Data Synchronization

Sync Queue Implementation

Background Sync

Offline Data Management

Caching Strategy with React Hook

Optimistic Updates

Service Workers

Basic Service Worker Setup

Offline UI Patterns

Offline Banner

Sync Status Indicator

Testing Offline Functionality

Best Practices

1. Cache Intelligently

2. Provide Clear Feedback

3. Queue Operations

4. Handle Conflicts

5. Expire Old Cache

Stuck somewhere? Our
team is ready to assist you.

Navigation

Help

Resources

Overview​

Why Offline Support Matters​

Offline Strategies​

1. Cache-First Strategy​

2. Network-First Strategy​

3. Offline-First Strategy​

Detecting Network Status​

Using Network API​

Using Browser API​

Local Storage Solutions​

LocalStorage​

IndexedDB​

Capacitor Storage​

Data Synchronization​

Sync Queue Implementation​

Background Sync​

Offline Data Management​

Caching Strategy with React Hook​

Optimistic Updates​

Service Workers​

Basic Service Worker Setup​

Offline UI Patterns​

Offline Banner​

Sync Status Indicator​

Testing Offline Functionality​

Best Practices​

1. Cache Intelligently​

2. Provide Clear Feedback​

3. Queue Operations​

4. Handle Conflicts​

5. Expire Old Cache​

Related Documentation​

Navigation

Help

Resources

Overview

Why Offline Support Matters

Offline Strategies

1. Cache-First Strategy

2. Network-First Strategy

3. Offline-First Strategy

Detecting Network Status

Using Network API

Using Browser API

Local Storage Solutions

LocalStorage

IndexedDB

Capacitor Storage

Data Synchronization

Sync Queue Implementation

Background Sync

Offline Data Management

Caching Strategy with React Hook

Optimistic Updates

Service Workers

Basic Service Worker Setup

Offline UI Patterns

Offline Banner

Sync Status Indicator

Testing Offline Functionality

Best Practices

1. Cache Intelligently

2. Provide Clear Feedback

3. Queue Operations

4. Handle Conflicts

5. Expire Old Cache

Related Documentation