pwa-sync

Offline-first data caching and mutation queue for PWAs, backed by Dexie (IndexedDB).

Install

pnpm add pwa-sync dexie

For React hooks, also install:

pnpm add dexie-react-hooks react

Usage

OfflineData

Caches data from a remote endpoint in IndexedDB. When online, fetches fresh data and updates the cache. When offline, serves from cache.

import Dexie from 'dexie'
import { OfflineData } from 'pwa-sync'

const db = new Dexie('mydb')
db.version(1).stores({
  items: 'id',
  syncMeta: 'endpoint',
})

const offlineData = new OfflineData(db.table('items'), db.table('syncMeta'), '/api/items')

const result = await offlineData.get()
// result.source → 'network' | 'cache'
// result.data   → T[]
// result.lastUpdate → Date

const status = await offlineData.status()
// status.lastUpdate → Date | null

OfflineQueue

A persistent mutation queue with automatic retries, exponential backoff, and online/offline awareness. Mutations are stored in IndexedDB and processed in FIFO order.

import Dexie from 'dexie'
import { OfflineQueue } from 'pwa-sync'

const db = new Dexie('mydb')
db.version(1).stores({
  submissions: 'id, createdAt',
})

const queue = new OfflineQueue(db.table('submissions'), '/api/submit')

// Add a mutation — it will be sent immediately if online, or queued for later
await queue.add({ name: 'New item' })

// Manually retry a failed item
await queue.retry(itemId)

// Remove an item from the queue
await queue.remove(itemId)

Items retry up to 3 times (configurable via the third constructor arg) with exponential backoff (max 5 minutes). 4xx errors (except 429) are treated as fatal and won't retry. 5xx and network errors will retry.

React Hooks

import { useQueueLength, useQueueItems } from 'pwa-sync/react'

function PendingBadge() {
  const count = useQueueLength(queue)
  return <span>{count ?? 0} pending</span>
}

function PendingList() {
  const items = useQueueItems(queue)
  // items is a live-updating array of PendingSubmission<T>
}

API

OfflineData<T>

• constructor(table, metaTable, endpoint) — Dexie tables for data and sync metadata, plus the fetch URL
• get() — Returns cached or fresh data
• status() — Returns { lastUpdate: Date | null }
• clear() — Clears cached data and metadata

OfflineQueue<T>

• constructor(queue, endpoint, maxAttempts?) — Dexie table, POST endpoint, max retries (default 3)
• add(payload) — Enqueue a mutation
• remove(id) — Remove an item by ID
• retry(id) — Reset a failed item for retry
• clear() — Clear the entire queue
• length() — Returns the number of queued items
• process() — Manually trigger queue processing

React (pwa-sync/react)

• useQueueLength(queue) — Live count of queued items
• useQueueItems(queue) — Live array of PendingSubmission<T>

License

MIT