How to handle routing in Angular 5+ Service Workers?

Question

In previous versions of the Angular service worker implementation, one of the config options was "routing". This can be seen in this unanswered SO question, was referenced in this Angular CLI issue, and the best remaining documentation seems to be the blog post by Stephen Fluin (on the Angular team), as well as the I/O talk from Alex Rickabaugh (from Google).

With Angular 5, the ServiceWorkerModule has been well built-out, and most of the configuration can now be handled using the ngsw-config.json file. However, there is no longer any mention of how to handle redirection for routes, anywhere in the angular.io guide, or in the documentation. So I end up with the following problem: when I have visited my app and go offline, I can still access the app when visiting it directly: https://jackkoppa.github.io/cityaq-sw-issue. However, upon load the app redirects to the search route, and most users would be trying to load from a URL like https://jackkoppa.github.io/cityaq-sw-issue/search?cities=Shanghai (for simplicity, I'm just talking about Chrome desktop & mobile, for now, and in Incognito when possible).

When you try to visit that URL while offline, you immediately get 504 - Gateway Timeout. This is happening because the service worker has only cached the index, and doesn't know that other routes should redirect to the index so that it can load. I'm confident that previous iterations of the Angular service worker implementation could have handled this scenario, by setting up redirects to the index for given routes. Is there a way to handle this redirect in the current, Angular 5+ ngsw-config.json, or in the generated ngsw.json file? Barring that, how should a workaround be handled in a separate service worker JS file?

Answer 1

TL;DR: I've identified at least two issues causing breakage in my case; you can use this build script for now to try my fix, and see the app work offline here. Further testing & pull requests needed.

---

While I've been unable to find a documented answer, here's what I've been able to find thus far, in stepping through the ngsw-worker.js file, as well as reading the @angular/service-worker commit history.

The new ServiceWorkerModule approach to "routing" is to take any "navigation" request (i.e. a non-index route on the same domain), and re-run the handleFetch method, but now pointing to the index.html request (source). This should work fine, given an SPA should be able to redirect to the URL once it has retrieved its cached files for the index.

So the problems that are causing my site above to fail when offline must not be directly related to routing, and I've found 2 thus far. Correcting these with a workaround has allowed me to get my app working mostly as expected. With the repro steps in the original question, cityaq is now working, while I've reproduced the original, failing site at cityaq-sw-issue.

The issues:

1. Hosted versions of an Angular app, where the --base-href flag is set from the CLI, list absolute URLs for their service worker resources. When comparing requests to these resources, ngsw-worker.js is expecting relative URLs

   • source
   • I'm fairly confident this issue needs to be resolved, and I'll be working on a pull request to fix it. It happens because the baseHref is getting included in the resource URLs when ngsw.json is generated (source)

2. Of the 3 available "states" that the ngsw-worker.js can be in, in my experience, EXISTING_CLIENTS_ONLY seems to bet set incorrectly.

   • source 1, source 2
   • I'm less confident about this change, because I haven't been able to consistently see what causes this state. However, if & when the service worker enters this state, ngsw-worker.js will no longer attempt to retrieve cached resources (source), and in my testing under what seem to be "correct" circumstances, the app still enters this state even when the only change is removing an internet connection

While I put together a PR for issue #1, and wait for some help understanding issue #2, I'm using a workaround build script to modify ngsw-worker.js after it's generated. Warning: it's ugly & definitely modifies the intended "safe" behavior of setting EXISTING_CLIENTS_ONLY. However, for my app, it does allow correct offline performance both when running locally (http-server), and deploying to a live URL (GitHub pages, in my case).

To use the workaround: (Angular 5, tested w/ Angular 5.2.1)

1. npm install replace-in-file --save-dev
2. Include this script in your app, e.g. at build/fix-sw.js
3. In your package.json:

"scripts": {
   ...
   "sw-build": "ng build --prod && node build/fix-sw",
   "sw-build-live": ng build --prod --base-href https://your-url.com/ && node build/fix-sw"
   ...
}

4. To run locally

npm run sw-build
cd dist
http-server -p 8080

5. And to prepare a build for your live URL, before sending to a server (e.g. with angular-cli-ghpages)

npm run sw-build-live

Answer 2

I just had to deal with this for several days, though I'm not using routes, just a non-root base href. I'll share the configuration that's working for me, which has at least a chance of working for routed apps, because I get my app whenever I try to use route/ngsw/state to debug.

1. This is a "sub-app" off the main site, and links direct to http(s)://<host>/route/index.html
2. manifest.webmanifest is just served, so doesn't know or care what angular is doing to things, so it's expliclty including the sub route.

   "scope": "/route/",
   "start_url": "/route/index.html",
   

3. angular.json has baseHref set, because the whole app is served under this and that's what base-href is for:

   "baseHref": "/route/",
   

4. ngsw-config.json was the tricky one, because it uses its patterns to find files in the deployment folder to add to ngsw.json, so things like adding baseHref there or using relative paths breaks it. This file needs to think and look like it's being served from the root, e.g.:

   "index": "/index.html",
   ...
     "files": [
       "/index.html",
       "/*.js"
     ]
   

5. The Angular CLI will add baseHref in ngsw.json, giving you asset URLs and hash keys like "/route/index.html"
6. Your app will make requests like "/route/index.html" and "/route/main.js" because of the baseHref, which match the keys under which they are hashed and are now actually cached.
7. The service worker is correctly registered under /route/, so it will a.) attempt to handle requests and b.) find them in its caches when you go offline.

One of the things that made this so damn difficult was how many different ways to specify paths and bases there are, and that some are quite accommodating while others are very strict. If your deployment is broken, you can't actually use the built-in debugging, and you can't just turn on debug logging like with a sane module. The docs are incredibly sparse, especially compared to how well things like Directives and Templates are covered.

Still, this was 1000% easier to get working than any other solution I found.

Side note: If you use ServiceWorkerModule.register('ngsw-worker.js', { enabled: true }) and move "serviceWorker": true, and "ngswConfigPath": "ngsw-config.json" up to the general build options in angular.json instead of under the prod config, you don't have to wait 5 extra minutes for a prod build when debugging.

P.S. Props to OP's sleuthing which got my breakpoints in the right places.