Writing a PWA with Aurelia

manifest.json

Once you've build the app, you can add the manifest.json file. To do so add in your index.html or index.ejs:

<link rel="manifest" href="/manifest.json">

Then in the static/ folder (if you are not using webpack as configured by aurelia-cli, you may need to adapt this, the goal is to have this file in the root of the build files next to the index.html file), you can create the manifest.json file. Below is an example, you can adapt it to your needs. It also has more properties, see the documentation to view all its possibilities.

{
    "name": "aurss – RSS reader",
    "short_name": "aurss",
    "start_url": "/",
    "scope": ".",
    "display": "standalone",
    "background_color": "#FFF",
    "theme_color": "#493174",
    "description": "RSS reader for TTRSS",
    "dir": "ltr",
    "lang": "en-US",
    "orientation": "portrait-primary",
    "icons": [{
        "src": "/icons/aurss.96x96.png",
        "type": "image/png",
        "sizes": "96x96"
    }, {
        "src": "/icons/aurss.512x512.png",
        "type": "image/png",
        "sizes": "512x512"
    }]
}

ServiceWorker

Then, include the service worker:

1. Create a file named sw.js in your src folder. Leave it empty for now.

2. Register the worker in the app.js with:

   if ('serviceWorker' in navigator) {
       runtime.register()
           .then((registration) => this.logger.info('Service worker is registered', registration))
           .catch((registrationError) => this.logger.error(
               'Service worker failed to register', registrationError,
           ));
   } else {
       this.logger.info('Service worker is not available in this browser.');
   }
   

3. Make sure it will be copied when you build the application next to the index.html. For instance, with webpack, you can use this plugin (which will also be handy later for caching so I recommend that you use it or something similar).

Now the SW is bootstrapped, we can start to use it to:

• Cache the shell of the app (ie the files it needs to work) and provide offline support. This is done once the SW is installed, so when the installed event has been fired (self represent the SW instance):

  // Name of our static cache.
  const staticCachePrefix = 'static';
  // Update this each time you app shell changes.
  // This way, the SW will have changed and get reinstalled
  // allowing for the new files to be cached.
  const VERSION = '1.0.0';
  const staticCacheName = `${staticCachePrefix}-${VERSION}`;
  
  self.addEventListener('install', (event) => {
      log('Installing SW version:', VERSION);
      // waitUntil is there to make the sure SW is neither paused nor stopped
      // while we expect it to do some work until the promise we passed to it completes.
      // See: https://stackoverflow.com/a/37906330
      event.waitUntil(
          caches.open(staticCacheName)
              .then(cache => {
                  console.log('Caching app shell');
                  // serviceWorkerOption comes from serviceworker-webpack-plugin.
                  // Adapt if needed.
                  cache.addAll(serviceWorkerOption.assets);
              }),
      );
  });
  

  You can then use in your app.js file, in the constructor, something like the code below to display notification to the user about online/offline status:

  this.onOffline = () => this.store.dispatch(isOffline.name);
  this.onOnline = () => this.store.dispatch(isOnline.name);
  
  if (!navigator.onLine) {
      this.store.dispatch(isOffline.name);
  } else {
      this.store.dispatch(isOnline.name);
  }
  
  window.addEventListener('offline', this.onOffline);
  window.addEventListener('online', this.onOnline);
  

• Catch network requests, for instance to implement dynamic caching.

  self.addEventListener('fetch', (event) => {
      // Let the browser do its default thing
      // for non-GET requests.
      if (event.request.method !== 'GET') {
          return;
      }
  
      event.respondWith(
          caches.match(event.request)
              .then((response) => {
                  return response || fetch(event.request);
              }),
      );
  });
  

• When offline, you can store data in indexDB to send it as soon as the browser gets online again. To do this, you must listen to the sync event in the SW. You can take inspiration from this code for the SW part and from these utility functions (see a usage here) to achieve this.

self.addEventListener('activate', (event) => {
    console.log('Cleaning old cache shell');
    event.waitUntil(
        caches.keys()
            .then((keylist) => Promise.all(
                keylist
                    .filter((key) => key !== staticCacheName && key.startsWith(staticCachePrefix))
                    .map((key) => caches.delete(key))
            )),
    );
});

Finally, you should test you app with lighthouse to check it actually is a PWA. The tool will also check for performance which is a good thing. In the Chrome dev tools, go to the Audit tab, verify that Progressive Web App is checked under the audit section and run the audit. The report should tell you that you have indeed created a PWA (and if not, what you are missing).