Offline-first : Service Worker et cache

ng add @angular/pwa
# ajoute @angular/service-worker, ngsw-config.json, un manifeste, des icônes et provideServiceWorker()
ng build   # le worker ne tourne que dans les builds de production, en HTTPS (ou sur localhost)

{
  "$schema": "./node_modules/@angular/service-worker/config/schema.json",
  "index": "/index.html",
  "assetGroups": [
    {
      "name": "app-shell",
      "installMode": "prefetch",
      "resources": { "files": ["/favicon.ico", "/index.html", "/*.css", "/*.js"] }
    },
    {
      "name": "assets",
      "installMode": "lazy",
      "updateMode": "prefetch",
      "resources": { "files": ["/assets/**", "/*.(svg|png|webp|woff2)"] }
    }
  ],
  "dataGroups": [
    {
      "name": "prices",
      "urls": ["/api/prices/**"],
      "cacheConfig": { "strategy": "freshness", "timeout": "3s", "maxSize": 50, "maxAge": "1h" }
    },
    {
      "name": "catalogue",
      "urls": ["/api/products/**"],
      "cacheConfig": {
        "strategy": "performance",
        "maxSize": 200,
        "maxAge": "7d",
        "refreshAhead": "1d"
      }
    }
  ]
}

import { ApplicationRef, Component, DestroyRef, inject, signal } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { SwUpdate, type VersionReadyEvent } from '@angular/service-worker';
import { filter, interval } from 'rxjs';

@Component({
  selector: 'app-update-banner',
  template: `
    @if (ready()) {
      <div role="status">
        Une nouvelle version est prête.
        <button type="button" (click)="reload()">Recharger</button>
      </div>
    }
  `,
})
export class UpdateBanner {
  private readonly updates = inject(SwUpdate);
  protected readonly ready = signal(false);

  constructor() {
    if (!this.updates.isEnabled) return; // mode dev, ou un navigateur sans Service Worker
    const destroyRef = inject(DestroyRef);

    this.updates.versionUpdates
      .pipe(
        filter((e): e is VersionReadyEvent => e.type === 'VERSION_READY'),
        takeUntilDestroyed(destroyRef),
      )
      .subscribe(() => this.ready.set(true)); // demander ; ne pas recharger au milieu d’un formulaire

    // les fichiers de la version en cours ont disparu du serveur : seul un rechargement s’en sort
    this.updates.unrecoverable
      .pipe(takeUntilDestroyed(destroyRef))
      .subscribe(() => document.location.reload());

    // un onglet qui reste ouvert des jours doit aussi vérifier de temps en temps
    const appRef = inject(ApplicationRef);
    void appRef.whenStable().then(() =>
      interval(6 * 60 * 60 * 1000)
        .pipe(takeUntilDestroyed(destroyRef))
        .subscribe(() => void this.updates.checkForUpdate()),
    );
  }

  protected reload(): void {
    document.location.reload(); // la nouvelle version démarre au prochain chargement de la page
  }
}

import { HttpClient, HttpContext } from '@angular/common/http';
import { DOCUMENT, Service, computed, effect, inject, signal, untracked } from '@angular/core';
import { firstValueFrom } from 'rxjs';
import { IDEMPOTENCY_KEY } from './idempotency'; // voir la page sur les mises à jour optimistes
import { injectOnline } from './online';

interface Pending {
  key: string; // Idempotency-Key, générée UNE SEULE FOIS quand l’utilisateur enregistre
  url: string;
  body: unknown;
}

const STORAGE = 'outbox';

@Service()
export class Outbox {
  private readonly http = inject(HttpClient);
  private readonly storage = inject(DOCUMENT).defaultView?.localStorage; // undefined pendant le SSR
  readonly online = injectOnline();
  readonly items = signal<readonly Pending[]>(JSON.parse(this.storage?.getItem(STORAGE) ?? '[]'));
  readonly waiting = computed(() => this.items().length);
  private flushing = false;

  constructor() {
    // survit à un rechargement (IndexedDB si les données sont volumineuses ou qu’un worker doit les lire)
    effect(() => this.storage?.setItem(STORAGE, JSON.stringify(this.items())));
    effect(() => {
      if (this.online()) untracked(() => void this.flush());
    });
  }

  save(url: string, body: unknown): void {
    this.items.update((list) => [...list, { key: crypto.randomUUID(), url, body }]);
    if (this.online()) void this.flush();
  }

  /** Une à la fois, dans l’ordre. Un échec arrête la file ; le prochain "online" la relance. */
  private async flush(): Promise<void> {
    if (this.flushing) return;
    this.flushing = true;
    try {
      while (this.online() && this.items().length) {
        const [next] = this.items();
        await firstValueFrom(
          this.http.post(next.url, next.body, {
            context: new HttpContext().set(IDEMPOTENCY_KEY, next.key),
          }),
        );
        this.items.update((list) => list.slice(1));
      }
    } catch {
      // toujours hors ligne, ou le serveur est en panne : l’élément reste en tête de file
    } finally {
      this.flushing = false;
    }
  }
}

ng add @angular/pwa              worker + manifeste + ngsw-config.json (builds de production uniquement)
registrationStrategy             'registerWhenStable:30000' : après le premier rendu
assetGroups prefetch             le shell de l’app : index.html, JS, CSS, disponibles hors ligne
assetGroups lazy                 images, polices : mises en cache à la première utilisation
dataGroups freshness + timeout   le réseau d’abord ; plus lent que timeout → réponse depuis le cache
dataGroups performance           le cache d’abord ; refreshAhead rafraîchit en arrière-plan avant maxAge
maxAge                           limite stricte : les entrées plus anciennes sont jetées, même hors ligne
SwUpdate.versionUpdates          VERSION_READY → demander à l’utilisateur, recharger au clic
SwUpdate.unrecoverable           les fichiers de l’ancienne version ont disparu → recharger
checkForUpdate()                 périodiquement, pour les onglets ouverts pendant des jours
CDN / cache HTTP                 ngsw.json et ngsw-worker.js : no-cache, jamais immutable
navigator.onLine                 false est certain, true veut seulement dire « il y a un réseau »
écritures hors ligne             outbox : ordonnée, persistée, chacune avec une Idempotency-Key