Offline-first: Service Worker & Caching

ng add @angular/pwa
# fügt @angular/service-worker, ngsw-config.json, ein Manifest, Icons und provideServiceWorker() hinzu
ng build   # der Worker läuft nur in Production-Builds, über HTTPS (oder auf 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">
        Eine neue Version ist bereit.
        <button type="button" (click)="reload()">Neu laden</button>
      </div>
    }
  `,
})
export class UpdateBanner {
  private readonly updates = inject(SwUpdate);
  protected readonly ready = signal(false);

  constructor() {
    if (!this.updates.isEnabled) return; // Dev-Modus oder ein Browser ohne 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)); // fragen; nicht mitten in einem Formular neu laden

    // die Dateien der laufenden Version sind vom Server verschwunden: nur ein Reload hilft
    this.updates.unrecoverable
      .pipe(takeUntilDestroyed(destroyRef))
      .subscribe(() => document.location.reload());

    // ein Tab, der tagelang offen bleibt, muss auch ab und zu nachsehen
    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(); // die neue Version startet beim nächsten Laden der Seite
  }
}

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'; // siehe die Seite zu optimistischen Updates
import { injectOnline } from './online';

interface Pending {
  key: string; // Idempotency-Key, EINMAL erzeugt, wenn der Nutzer speichert
  url: string;
  body: unknown;
}

const STORAGE = 'outbox';

@Service()
export class Outbox {
  private readonly http = inject(HttpClient);
  private readonly storage = inject(DOCUMENT).defaultView?.localStorage; // undefined während 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() {
    // übersteht einen Reload (IndexedDB, wenn die Daten groß sind oder ein Worker sie lesen muss)
    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();
  }

  /** Eins nach dem anderen, in Reihenfolge. Ein Fehler stoppt die Warteschlange; das nächste "online" setzt sie fort. */
  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 {
      // noch offline oder der Server ist down: das Element bleibt vorne in der Reihe
    } finally {
      this.flushing = false;
    }
  }
}

ng add @angular/pwa              Worker + Manifest + ngsw-config.json (nur Production-Builds)
registrationStrategy             'registerWhenStable:30000': nach dem ersten Rendern
assetGroups prefetch             die App-Shell: index.html, JS, CSS, offline verfügbar
assetGroups lazy                 Bilder, Fonts: beim ersten Gebrauch gecacht
dataGroups freshness + timeout   zuerst Netzwerk; langsamer als timeout → Antwort aus dem Cache
dataGroups performance           zuerst Cache; refreshAhead aktualisiert vor maxAge im Hintergrund
maxAge                           harte Grenze: ältere Einträge fliegen raus, auch offline
SwUpdate.versionUpdates          VERSION_READY → den Nutzer fragen, beim Klick neu laden
SwUpdate.unrecoverable           die Dateien der alten Version sind weg → neu laden
checkForUpdate()                 regelmäßig, für Tabs, die tagelang offen bleiben
CDN / HTTP-Cache                 ngsw.json und ngsw-worker.js: no-cache, nie immutable
navigator.onLine                 false ist sicher, true heißt nur „es gibt ein Netzwerk“
Schreiben offline                Outbox: geordnet, persistiert, jeweils mit Idempotency-Key