SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscapacitor-offline-first

capacitor-offline-first

Design & creation

View repository

Updated 10-13 22:01

About this skill

Offline-First Capacitor Apps

When to Use

TRIGGER when:

  • The app must read and write while offline and sync later
  • Choosing local storage (Preferences vs SQLite vs IndexedDB) for user data
  • Writes are duplicated, lost, or overwritten during sync
  • Cached data vanishes on iOS after low-storage events
  • A service worker was added and native plugins stopped working (Plugin not implemented)

Do not use:

  • Replacing @capacitor-community/sqlite / Ionic secure storage: sqlite-to-fast-sql
  • Getting new web code to devices (OTA): capgo-live-updates
  • Encryption key storage, SSL pinning: capacitor-security
  • Query speed / bridge overhead tuning: capacitor-performance

Decisions (make these before writing code)

Question Default answer
Where does UI read from? Local DB only. Network writes into the DB; UI observes the DB.
Storage for records SQLite via @capgo/capacitor-fast-sql
Storage for small settings / tokens @capacitor/preferences (not for secrets; see capacitor-security)
localStorage / IndexedDB Transient only: iOS can evict WebView storage under pressure
App shell offline Already offline: Capacitor bundles web assets in the binary (or Capgo live-update bundle). No service worker needed.
Service worker in native builds Avoid. Android SW blocks Capacitor plugin injection; iOS SW needs WKAppBoundDomains, which also blocks injection unless ios.limitsNavigationsToAppBoundDomains is set. Keep SW for the PWA build only.
IDs Client-generated UUIDs (crypto.randomUUID()), so offline creates need no server round trip
Conflict policy Ask the user/product owner: last-write-wins per record, per-field merge, or server-authoritative with user review
Deletes Soft delete (tombstone) until the server acknowledges

Workflow

  1. Inspect: current storage (localStorage, @capacitor/preferences, other SQLite plugins), API shape (does it support updated_since / version fields / idempotency keys?), auth refresh flow, existing service worker registration.
  2. Report the plan (schema, outbox, conflict policy) to the user before invasive changes. For large apps, list each entity as a TODO.
  3. Install: npm install @capgo/capacitor-fast-sql @capacitor/network && npx cap sync, then the platform setup in references/fast-sql-setup.md (required: iOS ATS local networking, Android localhost cleartext).
  4. Schema + outbox: references/sync-engine.md.
  5. Triggers for sync: app start, networkStatusChange -> connected, App resume, after each local write (debounced), optional background task.
  6. UI: show pending count / last synced time; never block a write on the network.
  7. Verify (below).

Only load a reference when its topic is in play.

Minimal shape

import { FastSQL } from '@capgo/capacitor-fast-sql';
import { Network } from '@capacitor/network';
import { App } from '@capacitor/app';

const db = await FastSQL.connect({ database: 'app' });
await db.execute(`CREATE TABLE IF NOT EXISTS outbox (
  id TEXT PRIMARY KEY, entity TEXT NOT NULL, op TEXT NOT NULL,
  payload TEXT NOT NULL, created_at INTEGER NOT NULL, attempts INTEGER NOT NULL DEFAULT 0
)`);

export async function saveTodo(todo: Todo) {
  await db.transaction(async (tx) => {
    await tx.run('INSERT OR REPLACE INTO todos (id, text, done, updated_at, dirty) VALUES (?, ?, ?, ?, 1)',
      [todo.id, todo.text, todo.done ? 1 : 0, Date.now()]);
    await tx.run('INSERT INTO outbox (id, entity, op, payload, created_at) VALUES (?, ?, ?, ?, ?)',
      [crypto.randomUUID(), 'todo', 'upsert', JSON.stringify(todo), Date.now()]);
  });
  void sync(); // fire and forget; sync() is single-flight
}

Network.addListener('networkStatusChange', (s) => { if (s.connected) void sync(); });
App.addListener('resume', () => void sync());

The data row and its outbox entry are written in one transaction so a crash cannot leave one without the other.

Traps

  • Network.getStatus().connected === true does not mean the API is reachable (captive portals, VPN, server down). Treat fetch failures as offline; use connected only as a hint to retry.
  • networkStatusChange can fire several times in a row; make sync() single-flight.
  • Send an idempotency key (the outbox row id) with every mutation; retries after a timeout otherwise duplicate records.
  • Process the outbox in order per entity; a delete must not overtake its create.
  • Advance the pull cursor using the server's timestamp/version from the response, never the device clock.
  • Auth tokens expire while offline: refresh before draining the outbox, and keep entries on 401 instead of dropping them.
  • Do not store large blobs in SQLite rows; save files with @capacitor/filesystem and keep the path in the DB.
  • iOS background execution is opportunistic. Background tasks help but cannot guarantee sync timing; foreground sync on resume is the reliable path.

Verification

  1. Airplane mode on device: create, edit, delete records; kill and relaunch the app; data is still there.
  2. Turn network back on: outbox drains to 0, server reflects all changes once (no duplicates).
  3. Conflict test: edit the same record on two devices offline, reconnect both; result matches the chosen policy.
  4. Flaky network: Android emulator network throttling / iOS Network Link Conditioner (Settings -> Developer); retries back off, no data loss.
  5. Native checks:
grep -rn "serviceWorker.register" src/ | grep -v "isNativePlatform"   # should be empty or web-guarded
/usr/libexec/PlistBuddy -c "Print :NSAppTransportSecurity:NSAllowsLocalNetworking" ios/App/App/Info.plist
grep -n "networkSecurityConfig\|usesCleartextTraffic" android/app/src/main/AndroidManifest.xml
  1. Inspect the DB: SELECT COUNT(*) FROM outbox exposed in a debug screen, or pull the file (adb exec-out run-as com.example.app ls databases/).

Error Handling

Error / symptom Cause Fix
"CapgoCapacitorFastSql" plugin is not implemented on android / Plugin not implemented Service worker or WKAppBoundDomains blocking injection, or missing npx cap sync Remove SW from native build / set ios.limitsNavigationsToAppBoundDomains; run npx cap sync
iOS: The resource could not be loaded because the App Transport Security policy requires the use of a secure connection Fast SQL localhost transport blocked by ATS Add NSAllowsLocalNetworking
Android: CLEARTEXT communication to localhost not permitted by network security policy Cleartext to localhost blocked Add network_security_config.xml localhost exception
SQLITE_CONSTRAINT: UNIQUE constraint failed during pull Server row id already exists locally Use INSERT ... ON CONFLICT(id) DO UPDATE
database is locked Parallel writers / long transaction Serialize writes; keep transactions short; single-flight sync
Data gone after iOS storage pressure Stored in localStorage / IndexedDB Move to SQLite
Duplicate server records after reconnect Retried POST without idempotency key Send outbox id as Idempotency-Key; server dedupes

Resources