@angular/service-worker

The Angular Service Worker (NGSW): an opinionated, declarative service worker for offline support and asset caching. Driven by an ngsw-config.json manifest rather than handwritten SW code.

Purpose

@angular/service-worker exists so applications can declare their caching behavior in JSON and get a working PWA without writing service-worker JavaScript. It provides:

• A driver service worker that interprets ngsw-config.json.
• A runtime API (SwUpdate, SwPush) that the application uses to react to updates and push notifications.
• A build-time tool (the @angular/service-worker/cli library, invoked by @angular/build) that produces ngsw.json from the config and the build output.

Directory layout

packages/service-worker/
├── src/
│   ├── module.ts          # ServiceWorkerModule + provideServiceWorker
│   ├── push.ts            # SwPush
│   ├── update.ts          # SwUpdate
│   ├── registration.ts    # SW registration plumbing
│   └── ...
├── worker/                # The driver SW that runs in the browser
│   └── src/
│       ├── driver.ts
│       ├── app-version.ts
│       ├── data.ts        # Data group caching policies
│       ├── assets.ts      # Asset group caching policies
│       └── ...
├── config/                # ngsw-config.json schema + parser
├── cli/                   # ngsw-config.json → ngsw.json build tool
└── public_api.ts

The split is deliberate: worker/ runs in the browser's service worker context (no DOM, restricted APIs); src/ runs in the page; cli/ runs at build time in Node.

Key abstractions

Type / function	File	What it is
provideServiceWorker	packages/service-worker/src/provider.ts	The standalone-providers entry.
SwUpdate	packages/service-worker/src/update.ts	API for observing updates and triggering activation.
SwPush	packages/service-worker/src/push.ts	API for push notifications.
Driver (in worker)	packages/service-worker/worker/src/driver.ts	The actual service worker logic.
AppVersion	packages/service-worker/worker/src/app-version.ts	Manages a single deployed app version's cache.

Update flow

sequenceDiagram
  participant App
  participant SwUpdate
  participant Driver as SW driver
  participant Server
  Driver->>Server: poll for ngsw.json hash change
  Server->>Driver: new ngsw.json
  Driver->>Driver: prefetch new assets, build new AppVersion
  Driver->>SwUpdate: emit VERSION_READY event
  SwUpdate->>App: notify available
  App->>SwUpdate: activateUpdate()
  SwUpdate->>Driver: trigger swap
  Driver->>App: reload with new version

The driver maintains multiple AppVersion instances simultaneously so that multiple open tabs can each finish their session before being upgraded.

Integration points

• @angular/core — uses provideAppInitializer to register the worker after app stabilization.
• @angular/build — generates ngsw.json from ngsw-config.json + build manifest at build time.
• @angular/router — the navigation strategy interacts with SW navigation requests; the SW handles index.html for navigation in single-page apps.

Entry points for modification

• A new caching strategy: extend packages/service-worker/worker/src/data.ts (data groups) or assets.ts (asset groups).
• A new config field: extend the schema in packages/service-worker/config/ and update the build-time generator in cli/.
• A new runtime API: add it under packages/service-worker/src/ and wire up the message bridge to the worker.