{"canonical_url":"https://engineer.company/glossary/progressive-web-app/","content_markdown":"# Progressive web app\n\n## What it is\n\nA progressive web app, also written Progressive Web App and usually shortened to\nPWA, is a website built so that a browser can install it and run it like an app:\nfrom its own icon, in its own window, and often with part of it still working\nwhen the network is gone. It stays an ordinary website the whole time. Nothing\ncomes from an app store, and the pages are the same HTML, CSS and JavaScript a\nbrowser would load in a tab.\n\nNo standard defines the term. What the standards define are the two parts it is\nbuilt from. The first is the web app manifest, a JSON file described by the\nW3C's Web Application Manifest, which gives the app a name, icons, a start URL\nand a display mode. That specification sets a low bar for who qualifies: “Any\nwebsite is an installable web application.” A browser can offer a way to install\none, and the installed app then opens with the manifest's settings applied. In\nthe `standalone` display mode it is meant to resemble a native application,\nwhich can mean a window of its own and an icon in the application launcher, and\nthe browser leaves out its standard interface, such as the URL bar.\n\nThe second part is the service worker, from the W3C's Service Workers\nspecification. It is a script the browser runs apart from the page, which sits\nbetween the page and the network, sees the requests the page makes and can\nanswer them from caches the script controls. That is what lets a web app keep\nserving its pages while offline. Those caches belong to the script: the\nspecification keeps them completely separate from the browser's ordinary HTTP\ncache, and they change only when the script changes them.\n\nThe Web Application Manifest never uses the word “progressive”, and the Service\nWorkers specification uses it once, in a note about how Chromium recognises a\nPWA. The Next.js guide to PWAs recommends progressive enhancement, so that the\napp still works well in a browser that does not support some of its PWA\nfeatures. Every part is optional in that sense. A browser that ignores the\nmanifest, or has no service worker support, still shows the website.\n\nA progressive web app is not a separate kind of website either. A single-page\napplication, a static site and a server-rendered one can each add a manifest and\na service worker. The term describes what a browser can do with a site after it\nhas loaded, not how its HTML is produced.\n\n## Why it matters\n\nThe Next.js guide makes the case in three points. Updates go out at once,\nwithout waiting for app store approval. One codebase serves every platform. And\nthe app gets features people expect from native apps, such as installing to the\nhome screen and push notifications. All three follow from the app still being a website: a new version can be published without a separate app-store release; when each device adopts it depends on caching and service-worker updates.\n\nOffline is the reason the service worker exists. The specification's own\nmotivation section says that web applications have traditionally assumed the\nnetwork is reachable, and that other application platforms consequently cope\nbetter with interrupted connections. Service workers give web applications a way\nto handle that interruption too. With one in place, a train in a tunnel or a\nship out of range of the coast no longer has to end in the browser's error page.\n\nThe two halves are independent. The Next.js guide notes that install prompts do\nnot need offline support, and the manifest specification has removed its own\n`serviceworker` member. An app can be installable with no service worker, and a\nservice worker can make an ordinary site work offline with no manifest at all.\n\nWhat both halves share is HTTPS. Next.js lists a site served over HTTPS as one\nof two things an app needs before it can be installed on a mobile home screen,\nthe other being a valid manifest. The Service Workers specification says service\nworkers must run in secure contexts, which in practice means HTTPS, with\nlocalhost allowed for development.\n\n## What it looks like in practice\n\nThree small files make a working PWA, all written for this article. The manifest\nnames the app, picks the display mode and lists its icons:\n\n```json\n{\n  \"name\": \"Field Notes\",\n  \"short_name\": \"Notes\",\n  \"start_url\": \"/\",\n  \"display\": \"standalone\",\n  \"icons\": [\n    { \"src\": \"/icon-192.png\", \"sizes\": \"192x192\", \"type\": \"image/png\" },\n    { \"src\": \"/icon-512.png\", \"sizes\": \"512x512\", \"type\": \"image/png\" }\n  ]\n}\n```\n\nEach page links the manifest and registers the service worker, but only in a\nbrowser that supports it:\n\n```html\n\u003clink rel=\"manifest\" href=\"/manifest.webmanifest\" /\u003e\n\u003cscript\u003e\n  if (\"serviceWorker\" in navigator) {\n    navigator.serviceWorker.register(\"/sw.js\");\n  }\n\u003c/script\u003e\n```\n\nAnd the service worker keeps a small set of files for offline use:\n\n```js\n// sw.js\nconst CACHE = \"shell-v2\";\nconst SHELL = [\"/offline.html\", \"/app.css\", \"/app.js\"];\n\nasync function precache() {\n  const cache = await caches.open(CACHE);\n  await cache.addAll(SHELL);\n}\n\nasync function dropOldCaches() {\n  const names = await caches.keys();\n  const old = names.filter((name) =\u003e name !== CACHE);\n  await Promise.all(old.map((name) =\u003e caches.delete(name)));\n}\n\nasync function respond(request) {\n  if (request.mode === \"navigate\") {\n    try {\n      return await fetch(request);\n    } catch {\n      return caches.match(\"/offline.html\");\n    }\n  }\n  const hit = await caches.match(request);\n  return hit ?? fetch(request);\n}\n\nself.addEventListener(\"install\", (event) =\u003e {\n  event.waitUntil(precache());\n});\n\nself.addEventListener(\"activate\", (event) =\u003e {\n  event.waitUntil(dropOldCaches());\n});\n\nself.addEventListener(\"fetch\", (event) =\u003e {\n  if (event.request.method !== \"GET\") return;\n  event.respondWith(respond(event.request));\n});\n```\n\nThe manifest uses `.webmanifest`, the file extension registered for it, and is\nserved with the media type `application/manifest+json`. The service worker sits\nat the root because its scope defaults to the directory the script is in, so a\nworker at `/js/sw.js` could only control pages under `/js/` unless the server\nsent a `Service-Worker-Allowed` header. When it installs, it opens a cache named\n`shell-v2` and stores the offline page, the stylesheet and the script.\n`addAll()` rejects if any of those files comes back with an error status, and\nbecause `waitUntil()` was handed that promise, the whole installation fails with\nit instead of leaving a half-filled cache behind. On activation it deletes every\ncache with another name. Page navigations go to the network first and fall back\nto the cached offline page when the network does not answer. Everything else is\nserved from the cache when it is there and fetched when it is not. Requests\nother than `GET` are left alone.\n\nThe company describes a full build of this on a real platform.\n[The portfolio entry](/portfolio/delivered-full-progressive-web-app-support/)\nexplains why it was needed: many of the platform's users are seafarers and field\nstaff on phones, often offline or on a weak connection, so the app had to\ninstall like a native one and keep working when the signal drops. It covers both\nhalves. The app installs to the home screen with icons in several sizes, a\nsplash screen and theme colours. The service worker is set up through the\nnext-pwa plugin, and Workbox runtime caching serves fonts, images, audio, video\nand CDN assets cache-first, since none of them change from one request to the\nnext, alongside HTTP cache-control headers. Because service workers need HTTPS,\nthe install and offline behaviour were tested over HTTPS on real devices. The\noutcome it reports is an app people install and go on using offline, with repeat\nvisits loading from the cache.\n\nThe install half also looks different from the reader's side. The site's\n[page on installing it as an app](/install/) walks through where each browser\nkeeps the command: the Share menu and Add to Home Screen in Safari on an iPhone,\na small icon on the right of the address bar in Chrome, Edge, Brave, Opera and\nVivaldi on a computer, and Add to Dock in Safari on macOS Sonoma or later. It\nalso states that iOS never suggests installing on its own. Firefox provides\nseparate web-app windows on Windows from version 143, or version 150 for\nMicrosoft Store installations, but not on macOS or Linux. The page is also clear\nabout what installing this site gives: an icon and a window, but no offline copy,\nbecause offline support needs a service worker.\n\n## Where it goes wrong\n\n**Users keep the old version.** According to the Service Workers specification,\ncache objects are not updated unless the author explicitly asks for it, and they\ndo not expire unless the author deletes them. A cache-first worker therefore\nserves yesterday's stylesheet until its script says otherwise. Put a version in\nthe cache name, change it whenever the cached files change, and delete the old\ncaches on activation, as the example does. Changing the script is what starts an\nupdate, because the browser compares the newly fetched `sw.js` byte for byte\nwith the installed one. Even then the new worker waits until no tab or window is\nusing the old one, unless it calls `skipWaiting()`, so a user who keeps a tab\nopen runs the previous version for as long as that tab stays open. The Next.js\nguide serves `sw.js` with `Cache-Control: no-cache, no-store, must-revalidate`,\nso that users always get the latest version of the worker itself.\n\n**It works on the laptop and not on the test phone.** `navigator.serviceWorker`\nexists only in secure contexts. On a page served over plain HTTP the usual\nfeature check is quietly false, the worker is never registered, and nothing on\nthe page says so. The specification lets browsers allow localhost, 127.0.0.0/8\nand ::1/128 for development, which is why a worker that runs on a developer's\nown machine can be missing when a phone opens the same app over HTTP from that\nmachine's address on the local network. Next.js offers\n`next dev --experimental-https` for local testing over HTTPS. Test install and\noffline behaviour on real devices, over HTTPS, before calling either one done.\n\n**A fetch listener that does nothing.** The Service Workers specification\nrecords that some sites register a `fetch` listener with an empty body only so\nthat Chromium will recognise them as a progressive web application. The\nspecification now detects listeners like `() =\u003e {}`, and it encourages browsers\nto warn that such listeners are unnecessary and may hurt performance. Write a\nhandler that answers requests, or leave the listener out.\n\n**Counting on an install prompt.** Whether to offer installation, and how, is up\nto the browser. Next.js says modern browsers show an install prompt\nautomatically once a site has a valid manifest and HTTPS, and advises against\nbuilding a custom install button on `beforeinstallprompt`, because that event\ndoes not work across browsers and platforms, Safari on iOS included. The\nmanifest specification has since removed the event altogether. The display mode\nand start URL are advisory as well: a browser that does not support `standalone`\nfalls back to `minimal-ui` and then to `browser`, an ordinary tab. Tell users\nhow to install, as the iOS instructions in the Next.js guide do, and design for\nthe app being opened in a tab.\n\n## Further reading\n\n- [Web Application Manifest](https://www.w3.org/TR/appmanifest/)\n  — the manifest format, its members, display modes, and what installing and\n  uninstalling mean.\n- [Service Workers](https://www.w3.org/TR/service-workers/)\n  — the worker's life cycle, scope, update rules, the secure-context\n  requirement and the Cache API.\n- [Web Application Manifest: Installable web applications](https://www.w3.org/TR/appmanifest/#installable-web-applications)\n  — how a browser installs a web application, launches it and lets the user\n  remove it again.\n- [Service Workers: Understanding cache lifetimes](https://www.w3.org/TR/service-workers/#cache-lifetimes)\n  — why cache objects never update or expire unless the script tells them to.\n- [How to build a Progressive Web Application (PWA) with Next.js](https://nextjs.org/docs/app/guides/progressive-web-apps)\n  — a manifest file, push notifications, install instructions for iOS, HTTPS\n  in development and security headers for the service worker.\n\n\u003chttps://engineer.company/glossary/progressive-web-app/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"A website a browser can install and keep running offline: the manifest and service worker behind it, the HTTPS rule, and four ways it goes wrong.","formats":{"gemtext":"https://engineer.company/glossary/progressive-web-app/index.gmi","gopher":"https://engineer.company/glossary/progressive-web-app/gophermap","html":"https://engineer.company/glossary/progressive-web-app/","json":"https://engineer.company/glossary/progressive-web-app/index.json","markdown":"https://engineer.company/glossary/progressive-web-app/index.md","pdf":"https://engineer.company/glossary/progressive-web-app/index.pdf"},"kind":"page","language":"en","title":"What is a progressive web app?","url":"https://engineer.company/glossary/progressive-web-app/","version":1}