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 Velloreth
The three requirements
- HTTPS
- A web app manifest
- 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
| Strategy | Behaviour |
|---|---|
| Cache first | the cache, then the network |
| Network first | the network, then the cache |
| Stale while revalidate | the cache, and refresh in the background |
| Network only | no cache |
| Cache only | no 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.
Related reading
For the related topics, see service-workers-explained and indexeddb-basics. For the broader context, caching-strategies-guide and lazy-loading-images.