Mode hors ligne PWA : Service Worker + IndexedDB en pratique

Extrait de vite.config.ts du POC terrain. Les deux options commentées sont indispensables en production et souvent omises dans les tutoriels.

VitePWA({
  registerType: 'autoUpdate',
  workbox: {
    globPatterns: ['**/*.{js,css,html,svg,png,woff2}'],
    navigateFallback: 'index.html',

    // Sans clientsClaim, le nouveau SW s'installe mais ne prend pas le contrôle
    // des onglets déjà ouverts : l'ancien SW (sans les nouveaux assets) reste actif
    // jusqu'au rechargement suivant. Résultat : page "hors connexion" au refresh offline.
    clientsClaim: true,

    // Vite hache les fichiers à chaque build (ex: index-Bi_bQYCK.js).
    // Sans cette option, l'ancien SW garde les URLs hachées de la version précédente
    // en cache → les nouveaux fichiers sont introuvables → 404 au chargement offline.
    cleanupOutdatedCaches: true,

    runtimeCaching: [
      {
        // Les requêtes Supabase (API + Storage) passent toujours par le réseau.
        // On ne met jamais en cache des données d'authentification ou des fichiers
        // utilisateur qui peuvent changer à tout moment côté backend.
        urlPattern: /^https:\/\/.*\.supabase\.co\//,
        handler: 'NetworkOnly',
      },
    ],
  },
  devOptions: {
    // Active le Service Worker en mode développement pour tester l'installabilité.
    // beforeinstallprompt ne se déclenche jamais sans SW actif.
    enabled: true,
  },
})

Stratégie choisie : CacheFirst pour l'app shell (fichiers statiques précachés par Workbox à l'installation), NetworkOnly pour toutes les requêtes vers Supabase. Pas de StaleWhileRevalidate sur les données utilisateur : on ne veut pas afficher des données périmées sur une application métier.

Chaque évolution du schéma déclenche une migration versionnée. Dexie applique automatiquement les migrations manquantes au démarrage de l'app : un utilisateur qui n'a pas ouvert l'app depuis 3 versions repassera par toutes les étapes dans l'ordre.

import Dexie, { type EntityTable } from 'dexie'

const db = new Dexie('pocTerrain') as Dexie & {
  interventions: EntityTable<Intervention, 'uuid'>
  syncQueue:     EntityTable<SyncQueueItem, 'id'>
  photos:        EntityTable<InterventionPhoto, 'uuid'>
}

// v1 → schéma initial
db.version(1).stores({
  interventions: 'uuid, syncStatus, createdAt',
  syncQueue:     '++id, type, status, itemId, createdAt, [itemId+type]',
})

// v3 → ajout table photos (aucun upgrade nécessaire, table vide)
db.version(3).stores({
  interventions: 'uuid, syncStatus, createdAt, status',
  syncQueue:     '++id, type, status, itemId, createdAt, [itemId+type]',
  photos:        'uuid, interventionUuid, createdAt',
})

// v5 → champ pinnedForOffline (cache hybride : fix une intervention hors ligne)
db.version(5).stores({
  interventions: 'uuid, syncStatus, createdAt, status',
  syncQueue:     '++id, type, status, itemId, createdAt, [itemId+type]',
  photos:        'uuid, interventionUuid, syncStatus, createdAt',
}).upgrade(tx =>
  tx.table('interventions').toCollection().modify((item: Intervention) => {
    if (item.pinnedForOffline === undefined) item.pinnedForOffline = false
  })
)

// v6 → champ storageUrl optionnel sur les photos (aucun upgrade nécessaire)
db.version(6).stores({ /* identique v5 */ })

Index composé [itemId+type] sur syncQueue : permet de dédupliquer les opérations en queue avec une requête where('[itemId+type]').equals([id, 'delete']) au lieu d'un scan complet de la table, ce qui est important quand la queue grossit en zone sans réseau prolongée.

La queue est un singleton module-level : elle est chargée une seule fois au premier import du composable et partagée entre tous les composants qui l'utilisent. syncStatus (computed) reflète l'état réel en temps réel.

// Singleton module-level : chargé dès le premier import, partagé partout
const queue = ref<SyncQueueItem[]>([])

const syncStatus = computed<'ok' | 'pending' | 'error'>(() => {
  if (queue.value.some(item => item.status === 'error')) return 'error'
  if (queue.value.length > 0) return 'pending'
  return 'ok'
})

async function enqueueCreate(itemId: string): Promise<void> {
  await db.syncQueue.add({ type: 'create', status: 'pending', itemId, createdAt: now() })
  await loadQueue()
}

async function enqueueUpdate(itemId: string): Promise<void> {
  // Déduplication : si un create/update est déjà en queue pour cet item,
  // inutile d'en empiler un autre : au moment du traitement on lira
  // toujours la dernière version de l'item depuis Dexie.
  const existing = await db.syncQueue.where({ itemId }).first()
  if (!existing) {
    await db.syncQueue.add({ type: 'update', status: 'pending', itemId, createdAt: now() })
  }
  await loadQueue()
}

async function enqueueDelete(itemId: string): Promise<void> {
  // Déduplique uniquement contre un delete existant pour le même item.
  // Un create/update déjà en queue reste (il sera traité avant, puis la
  // suppression sera exécutée dans l'ordre FIFO).
  const existingDelete = await db.syncQueue
    .where('[itemId+type]').equals([itemId, 'delete']).first()
  if (!existingDelete) {
    await db.syncQueue.add({ type: 'delete', status: 'pending', itemId, createdAt: now() })
  }
  await loadQueue()
}

Soft-delete sur les photos : quand un technicien supprime une photo hors ligne, on passe syncStatus à 'pending_delete' dans Dexie sans supprimer l'enregistrement. La vraie suppression (Storage + Supabase) se fait à la prochaine synchronisation.

La détection navigator.onLine seule est insuffisante : un appareil peut être "online" sur un réseau EDGE à 50 ko/s. Notre composable mesure la latence réelle par un HEAD vers l'origine pour qualifier la connexion en 'offline', 'slow' ou 'normal'.

// VueUse gère les événements online/offline et l'API Network Information
const { isOnline, type, effectiveType, downlink } = useVueNetwork()

async function check(): Promise<NetworkStatus> {
  const start = performance.now()
  await fetch(window.location.origin + '/', {
    method: 'HEAD',
    cache: 'no-store',
    signal: AbortSignal.timeout(5000),
  })
  const latency = Math.round(performance.now() - start)

  return {
    isOnline: isOnline.value,
    latency,                             // ms, mesuré activement
    connectionType: type.value,          // 'wifi' | 'cellular' | 'ethernet'...
    effectiveType: effectiveType.value,  // 'slow-2g' | '2g' | '3g' | '4g'
    downlink: downlink.value,            // Mbit/s estimé
    quality: latency > 2000 ? 'slow' : 'normal',
  }
}

// Re-déclenche check() à chaque changement online/offline détecté par VueUse
watch(isOnline, () => { check() })

La valeur seuil de 2000 ms est configurable. En dessous de ce seuil, la sync se lance immédiatement. Au-dessus, l'app priorise les données texte et diffère les uploads photos.