Skip to content
Velloreth
Web Development 3 min read

Progressive Web Apps: Offline, Installable and Fast

A PWA is a web app that installs and works offline. Learn the manifest, the service worker, the cache, and the install prompt.

By

The three requirements

  1. HTTPS
  2. A web app manifest
  3. A service worker

It is still a website, reachable by a URL.

The manifest

{
  "name": "My Blog",
  "short_name": "Blog",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#0f172a",
  "icons": [
    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

It is linked from the HTML.

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

display: standalone hides the browser chrome.

The icons are required for the install.

The service worker

// sw.js
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open('v1').then((cache) => cache.addAll(['/', '/offline.html']))
  );
});

self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request).then((cached) => cached || fetch(event.request))
  );
});

It intercepts the network requests from the page.

It can serve a cached response, so the app works offline.

It has no access to the DOM.

The registration

if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
}

The scope is the directory of the script, so a script at the root controls the whole site.

The caching strategies

StrategyBehaviour
Cache firstthe cache, then the network
Network firstthe network, then the cache
Stale while revalidatethe cache, and refresh in the background
Network onlyno cache
Cache onlyno network

Cache first is for a static asset.

Network first is for an API.

Stale while revalidate is a good default for a page.

The offline fallback

self.addEventListener('fetch', (event) => {
  if (event.request.mode === 'navigate') {
    event.respondWith(
      fetch(event.request).catch(() => caches.match('/offline.html'))
    );
  }
});

An offline fallback is what makes the app usable without a network.

A cached shell plus a network fetch is the common pattern.

The update

A service worker updates in the background.

self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((keys) =>
      Promise.all(keys.filter((k) => k !== 'v1').map((k) => caches.delete(k)))
    )
  );
});

A versioned cache is deleted on the activate.

A skipWaiting activates the new worker immediately, which can break a running page.

A prompt to reload is the safer pattern.

The install prompt

let deferredPrompt;

window.addEventListener('beforeinstallprompt', (event) => {
  event.preventDefault();
  deferredPrompt = event;
});

// Later, on a user action
deferredPrompt.prompt();

The criteria: HTTPS, a manifest with the required fields, a service worker with a fetch handler, and an engagement signal.

The app can defer the prompt and show it at a chosen moment.

The push notification

self.addEventListener('push', (event) => {
  const data = event.data.json();
  event.waitUntil(
    self.registration.showNotification(data.title, { body: data.body })
  );
});

A push needs a subscription and a server.

The permission must be requested on a user action, not on load.

The testing

The Lighthouse PWA audit checks the criteria.

The DevTools Application panel shows the manifest, the service worker and the cache.

An offline test in the Network panel confirms the fallback.

A cache clear is required between the tests, because a stale worker is confusing.

Common mistakes

No HTTPS. The service worker does not register.

A service worker that caches everything. A stale app.

No cache version. A stale asset.

A skipWaiting with no reload. A broken page.

No offline fallback. A blank page.

A permission request on load. A denied permission.

A manifest with no icon. No install.

A cache that grows forever. A storage limit.

No update path. A stuck version.

A service worker in development. A confusing cache.

A quotable summary

A progressive web app is a website with a web app manifest and a service worker, which makes it installable and able to work offline. The manifest controls the name, the icons and the display mode, the service worker intercepts the network and can serve a cache, and HTTPS is required because a service worker is powerful. A cache-first strategy is for a static asset, a network-first for an API, and an offline fallback is what makes the app usable without a network.

For the related topics, see service-workers-explained and indexeddb-basics. For the broader context, caching-strategies-guide and lazy-loading-images.

Frequently asked questions

What is a progressive web app?
A web application that uses a web app manifest and a service worker to be installable, to work offline, and to feel like a native app. It is still a website, so it is reachable by a URL and it needs no app store. The three requirements are HTTPS, a manifest and a service worker.
What is a service worker?
A script that runs in the background, separate from the page, and intercepts the network requests from the page. It can serve a cached response, so the app works offline, and it can handle a push notification and a background sync. It has no access to the DOM.
What is the web app manifest?
A JSON file that describes the app: the name, the icons, the start URL, the display mode and the theme colour. It is what makes the app installable and what controls the appearance when it is installed. It is linked from the HTML with a link tag.
Why does a PWA need HTTPS?
Because a service worker can intercept every request from the origin, so a malicious one could serve a fake page. HTTPS ensures the script is authentic. localhost is exempt for development.
What is the difference between a PWA and a native app?
A PWA is a website, so it is reachable by a URL, it updates instantly, and it needs no app store. A native app has deeper access to the device, such as the file system and the sensors, and it is distributed through a store. A PWA is the right choice for a content or a form app, and a native app for a heavy device integration.
What is the install prompt?
A browser prompt that offers to install the app, shown when the criteria are met: HTTPS, a manifest with the required fields, a service worker with a fetch handler, and an engagement signal. The app can defer the prompt and show it at a chosen moment with the beforeinstallprompt event.