Offline-first: Service Worker & caching

ng add @angular/pwa
# adds @angular/service-worker, ngsw-config.json, a manifest, icons and provideServiceWorker()
ng build   # the worker only runs in production builds, over HTTPS (or on 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">
        A new version is ready.
        <button type="button" (click)="reload()">Reload</button>
      </div>
    }
  `,
})
export class UpdateBanner {
  private readonly updates = inject(SwUpdate);
  protected readonly ready = signal(false);

  constructor() {
    if (!this.updates.isEnabled) return; // dev mode, or a browser without 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)); // ask; don't reload in the middle of a form

    // the files of the running version are gone from the server: the only way out is a reload
    this.updates.unrecoverable
      .pipe(takeUntilDestroyed(destroyRef))
      .subscribe(() => document.location.reload());

    // a tab that stays open for days also needs to check now and then
    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(); // the new version starts with the next page load
  }
}

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'; // see the page on optimistic updates
import { injectOnline } from './online';

interface Pending {
  key: string; // Idempotency-Key, generated ONCE when the user saves
  url: string;
  body: unknown;
}

const STORAGE = 'outbox';

@Service()
export class Outbox {
  private readonly http = inject(HttpClient);
  private readonly storage = inject(DOCUMENT).defaultView?.localStorage; // undefined during 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() {
    // survives a reload (IndexedDB if the data is large or a worker needs to read it)
    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();
  }

  /** One at a time, in order. A failure stops the queue; the next "online" resumes it. */
  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 {
      // still offline, or the server is down: the item stays first in line
    } finally {
      this.flushing = false;
    }
  }
}

ng add @angular/pwa              worker + manifest + ngsw-config.json (production builds only)
registrationStrategy             'registerWhenStable:30000': after the first render
assetGroups prefetch             the app shell: index.html, JS, CSS, available offline
assetGroups lazy                 images, fonts: cached on first use
dataGroups freshness + timeout   network first; slower than timeout → answer from the cache
dataGroups performance           cache first; refreshAhead refreshes before maxAge in the background
maxAge                           hard limit: older entries are thrown away, even offline
SwUpdate.versionUpdates          VERSION_READY → ask the user, reload on click
SwUpdate.unrecoverable           the old version's files are gone → reload
checkForUpdate()                 periodically, for tabs that stay open for days
CDN / HTTP cache                 ngsw.json and ngsw-worker.js: no-cache, never immutable
navigator.onLine                 false is certain, true only means "there is a network"
writes offline                   outbox: ordered, persisted, with an Idempotency-Key each