🔌 Offline-First Development Strategies

The Offline-First Mindset

Most apps are built network-first: they assume a connection and treat its absence as an error state. Offline-first inverts that assumption. The local device is the source of truth for the current session, the UI works whether or not there's a signal, and the network is used to sync in the background. Connectivity becomes a spectrum — great, poor, intermittent, none — rather than a binary.

💡 The elevator analogy: A network-first app is an elevator that traps you when the power cuts. An offline-first app switches to backup power — it still moves you safely to the next floor and keeps limited service running until main power returns. The failure is planned for, not fatal.

Choosing Client Storage

Offline-first lives or dies on client storage. Three APIs cover almost every need; match the tool to the data.

IndexedDB — the workhorse

IndexedDB is a transactional, indexed object database in the browser. Its native API is famously verbose (event-based). A realistic pattern wraps it in promises; in production most teams reach for a thin library like idb. Here's the raw shape so you understand what those libraries do:

function openDb() {
  return new Promise((resolve, reject) => {
    const req = indexedDB.open('app-db', 1);
    req.onupgradeneeded = () => {
      const db = req.result;
      const store = db.createObjectStore('todos', { keyPath: 'id' });
      store.createIndex('pending', 'pending', { unique: false });
    };
    req.onsuccess = () => resolve(req.result);
    req.onerror = () => reject(req.error);
  });
}

async function putTodo(todo) {
  const db = await openDb();
  return new Promise((resolve, reject) => {
    const tx = db.transaction('todos', 'readwrite');
    tx.objectStore('todos').put(todo);
    tx.oncomplete = () => resolve();
    tx.onerror = () => reject(tx.error);
  });
}

import { openDB } from 'idb';

const db = await openDB('app-db', 1, {
  upgrade(db) {
    const store = db.createObjectStore('todos', { keyPath: 'id' });
    store.createIndex('pending', 'pending');
  }
});

await db.put('todos', todo);          // write
const all = await db.getAll('todos'); // read

Optimistic UI Updates

Waiting for a server round-trip before showing a change feels sluggish — and impossible offline. With optimistic UI you update the interface immediately, assuming success, then reconcile when (or if) the server responds. If it fails, you roll back.

async function addTodo(text) {
  const todo = {
    id: `tmp-${crypto.randomUUID()}`, // temporary local id
    text,
    completed: false,
    pending: true,                    // not yet confirmed by the server
    updatedAt: Date.now()
  };

  await putTodo(todo);   // 1. persist locally
  renderTodo(todo);      // 2. show it right away

  try {
    const res = await fetch('/api/todos', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(todo)
    });
    if (!res.ok) throw new Error(res.statusText);
    const saved = await res.json();
    await putTodo({ ...todo, id: saved.id, pending: false });
    reconcileId(todo.id, saved.id); // 3a. swap temp id for real id
  } catch {
    await enqueue({ type: 'create', payload: todo }); // 3b. queue for later
  }
}

Queue-Based Synchronization

When a write can't reach the server, don't drop it — append it to a durable sync queue in IndexedDB and drain the queue when connectivity returns (via the online event or a service-worker sync event). Failed items retry with exponential backoff and eventually land in a dead-letter state you can surface to the user.

async function processQueue() {
  const db = await openDb();
  const items = await getAll(db, 'syncQueue'); // ordered by timestamp

  for (const item of items) {
    try {
      const res = await fetch(item.url, {
        method: item.method,
        headers: { 'Content-Type': 'application/json' },
        body: item.body
      });
      if (!res.ok) throw new Error(`HTTP ${res.status}`);
      await remove(db, 'syncQueue', item.id); // success → drop it
    } catch (err) {
      item.retries += 1;
      if (item.retries >= 5) {
        item.status = 'failed';               // dead-letter
      } else {
        item.nextRetry = Date.now() + 2 ** item.retries * 1000; // backoff
      }
      await put(db, 'syncQueue', item);
      break; // stop on first failure; try again on next trigger
    }
  }
}

// Drain whenever the browser reports we're back online.
window.addEventListener('online', () => {
  processQueue().catch(console.error);
});

Conflict Resolution

When the same record is edited locally and remotely, their versions diverge. You need a policy. There is no universally right answer — it depends on the data and how much you trust each side.

// Last-write-wins reconciliation on sync.
async function reconcile(localItem) {
  const res = await fetch(`/api/items/${localItem.id}`);
  const serverItem = await res.json();

  if (serverItem.updatedAt > localItem.updatedAt) {
    await putTodo(serverItem);        // server is newer → adopt it
    return serverItem;
  }
  return uploadItem(localItem);        // local is newer → push it up
}

Network Status & UX

Communicate connectivity clearly but calmly. Use the online/offline events for the coarse state and the Network Information API for quality hints.

function updateStatus() {
  document.body.classList.toggle('is-offline', !navigator.onLine);
}
window.addEventListener('online', () => { updateStatus(); processQueue(); });
window.addEventListener('offline', updateStatus);
updateStatus();

// Optional: adapt to connection quality where supported.
const conn = navigator.connection;
if (conn) {
  conn.addEventListener('change', () => {
    if (conn.saveData || conn.effectiveType === '2g') {
      loadLowResAssets();  // be frugal on slow / save-data connections
    }
  });
}

Hands-on Exercise

async function addTodo(text) {
  const todo = { id: `tmp-${crypto.randomUUID()}`, text,
                 pending: true, updatedAt: Date.now() };
  await db.put('todos', todo);
  renderTodo(todo);

  if (!navigator.onLine) {
    return db.put('syncQueue', { id: todo.id, op: 'create', body: todo });
  }
  try {
    const res = await fetch('/api/todos', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(todo)
    });
    const saved = await res.json();
    await db.delete('todos', todo.id);
    await db.put('todos', { ...todo, id: saved.id, pending: false });
    reconcileId(todo.id, saved.id);
  } catch {
    await db.put('syncQueue', { id: todo.id, op: 'create', body: todo });
  }
}

window.addEventListener('online', () => processQueue());

Testing & Pitfalls

How to test offline behavior

• DevTools → Network → Offline / throttling to simulate no or poor connectivity.
• Real devices in airplane mode — emulators hide timing quirks.
• Drop the connection mid-operation to exercise your queue and rollback paths.
• Automated tests: mock fetch to reject and assert data was queued and later drained.

test('queues writes when offline', async () => {
  global.fetch = vi.fn().mockRejectedValue(new Error('offline'));
  const enqueue = vi.spyOn(queue, 'add');

  await addTodo('Buy milk');

  expect(enqueue).toHaveBeenCalledOnce();
  expect(fetch).toHaveBeenCalledTimes(1); // attempted, then queued on failure
});

Summary & Quiz

📚 Further Reading

• web.dev — The Offline Cookbook
• MDN — IndexedDB API
• idb — a tiny IndexedDB promise wrapper
• crdt.tech — Conflict-free Replicated Data Types

🚀 What's Next?

You've completed the PWA arc — architecture, service workers, and offline-first design. Next you'll bring the whole module together in the weekend project, combining a framework, state management, and these offline capabilities into one app.