Reliable Angular service worker operations depend on one release rule: deploy the generated ngsw.json manifest and every resource it describes as one coherent build. The worker treats those files as a versioned set, and a partial or stale deployment can make that set inconsistent. This guide covers production setup, cache policy, release sequencing, update messaging, diagnostics, and emergency deactivation. Angular describes its built-in worker as a basic caching utility for simple offline support with a limited feature set; teams needing advanced caching or offline behavior should assess native browser APIs. Production service-worker use requires HTTPS; localhost is the documented development exception. Angular’s service-worker overview
How Angular service worker deployment works
Angular CLI processes ngsw-config.json during ng build and generates ngsw.json. The manifest identifies the build resources covered by the worker and records hashes for those files. When the manifest changes, the worker recognizes a new application version. This makes the manifest and its referenced resources a release unit, not independent files to update whenever convenient. Angular configuration Angular service worker DevOps guidance
For a CLI application, Angular’s setup guide uses ng add @angular/pwa to add the service-worker package, configure build support and registration, and create ngsw-config.json. Build with ng build. The getting-started guide demonstrates serving a production build locally to test service-worker behavior; isolate or clear existing worker state if old cached content could confuse the result. Angular getting started
Configure asset and API caching intentionally
In ngsw-config.json, file resource groups cover build output files, generally in the project’s dist deployment directory. URL resource groups match runtime resources such as CDN-hosted files; unlike build files, these URLs do not have build-time content hashes. Data groups define caching for matching runtime data requests, such as API calls. Angular evaluates data groups in order, and the first matching group handles a request, so put specific matches ahead of broad patterns. Angular configuration
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minute#1 Best Overall
Asset installation: prefetch or lazy
| Choice | Behavior | Operational trade-off |
|---|---|---|
installMode: "prefetch" |
Download matching assets when installing a version. | Changed assets are ready sooner, at the cost of downloading them even if a user does not request them. |
installMode: "lazy" |
Download matching assets only when requested. | Can defer unnecessary downloads, but a first request may need the network. If using updateMode: "lazy", installMode must also be "lazy". |
API freshness: performance or freshness
| Strategy | How responses are chosen | Best fit and caution |
|---|---|---|
performance |
Serve a cached response when available; cache policy can permit it to remain usable for the configured age. | Favors speed and cached/offline availability. Choose an acceptable staleness window for the data. |
freshness |
Prefer the network; if the request exceeds its configured timeout, use the cache as fallback. | Favors current responses while allowing fallback. Set timeout and cache limits with request cost and offline needs in mind. |
Neither strategy makes arbitrary API data safe to cache. Match URLs narrowly, and choose age, size, timeout, and versioning based on the data’s freshness and privacy requirements. Check that authenticated or user-specific responses are appropriate for the caching behavior you configure. Angular configuration
Keep each release atomic and internally consistent
Angular’s DevOps guide warns that “A non-atomic deployment could result in the Angular service worker having visibility of partially updated content.” If a deployment exposes a new manifest alongside old assets, or the reverse, hash validation can fail. A mixed release can also break lazy-loaded chunks: an already open tab may still request a chunk from the build version it started with. Angular’s worker can enter a degraded or fallback mode rather than knowingly serving a broken application. Angular service worker DevOps guidance
- Publish the complete build and the matching
ngsw.jsonas one coordinated release. - Review origin, proxy, and CDN cache behavior so a client cannot receive stale pieces from different releases.
- Retain the resources needed by already-running clients when your deployment approach allows it; those clients can still request files from their original version.
- Include rollback and cache behavior in release planning, not just application-server readiness. Angular’s deployment reference covers CLI deployment considerations. Angular deployment
When Angular service worker updates reach users
When an application opens or refreshes, the worker checks ngsw.json. If it detects a new version, it downloads and caches that version. A tab already running normally remains on its current version; users receive the new version on a later load or reload. This separation helps keep one page’s code and resources consistent while it is open. Angular service worker DevOps guidance
Applications can use Angular’s SwUpdate service to check for updates, react when a version is available, and intentionally activate it. Communicating with the service worker
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
- Tell users an update is ready and offer a reload when it is safe.
- Avoid forcing a reload at a moment that could discard unsaved work; immediate activation is a product decision, not merely a deployment detail.
- Test update notifications across an old open tab and a newly deployed build so the message matches the actual activation behavior.
Debug Angular service worker and cache issues
Start with the application’s /ngsw/state endpoint. It exposes driver state, latest manifest hash, last update check, and a debug log. The states NORMAL, EXISTING_CLIENTS_ONLY, and SAFE_MODE describe service-worker operation and recovery conditions; they are not generic browser error labels. Then use browser developer tools to inspect service-worker registrations and Cache Storage. Angular notes that leaving developer tools open can keep a worker alive and alter lifecycle behavior; refresh the cache viewer if its contents appear out of date. Angular service worker DevOps guidance
Investigate an ngsw.json hash mismatch
- Compare the deployed
ngsw.jsonwith the files it references and verify that those files come from the same build. - Check whether a CDN, proxy, or browser-facing intermediary is serving a stale manifest or stale asset from another release.
- Inspect
/ngsw/statefor the latest manifest hash, driver state, and debug log; use browser tools to see which worker and cached resources are active. - Correct the release or intermediary cache inconsistency, then test with a clean browser profile or cleared site data so an older worker does not mask the result.
Bypass service-worker handling for a request
For a request the worker should not handle, Angular supports an ngsw-bypass request header or query parameter. Its value may be empty. Use the bypass narrowly for unsupported features or diagnosis rather than treating it as a fix for an inconsistent deployment. Angular service worker DevOps guidance
Deactivate a bad worker safely
Angular documents an emergency recovery method: remove or rename ngsw.json so the worker’s manifest request returns 404. On that response, the worker clears its caches and deregisters. Test this incident procedure in an environment where you can verify the result before relying on it in production. Angular service worker DevOps guidance
The package also includes safety-worker.js to help remove unwanted workers, but Angular warns that it cannot simply be registered directly as a replacement. Existing clients with cached state may not see the new index that registers it. Follow Angular’s current documented procedure rather than improvising a worker swap. Angular service worker DevOps guidance
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Know when the built-in worker is not enough
Angular characterizes its service worker as a basic caching utility for simple offline support, with a limited feature set, and says it is not accepting new features beyond security fixes. It remains a fit for straightforward application-resource caching and configured data groups. If requirements depend on advanced offline workflows or more specialized caching behavior, assess native browser APIs against those requirements rather than assuming the built-in worker will grow to cover them. Angular’s service-worker overview
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
