PWA glossarythe terms, defined
Plain-English definitions for every term you'll meet building a PWA. 58 entries.
actions (Notification option)
actions is an array option passed to showNotification(), e.g. { actions: [{ action: "reply", title: "Reply" }, { action: "dismiss", title: "Dismiss" }] }, that renders extra buttons on the notification itself. The service worker's notificationclick handler reads event.action to see which button, if any, the user pressed.
Read definitionactivate event (service worker)
The activate event fires after a service worker moves from "installed" to "activating", typically once the old worker's clients have all closed or skipWaiting() was called. Handlers commonly use it to clean up outdated Cache Storage entries left behind by earlier versions of the app shell.
Read definitionappinstalled event
appinstalled is a window event, listened for with window.addEventListener("appinstalled", () => { ... }), that fires after the browser has finished installing the PWA — regardless of whether the install was triggered via the native beforeinstallprompt flow or a browser menu item. It fires exactly once per successful install and carries no event detail beyond the fact that installation completed.
Read definitionbackground_color (manifest field)
background_color is a manifest field, for example "background_color": "#ffffff", used only for the auto-generated splash screen Android and Chromium OS show between tapping the app icon and the first paint. It should match your page's actual background to avoid a visible colour flash.
Read definitionbadge (Notification option)
badge is a field passed to showNotification(title, { badge: "/badge-72.png", ... }) that supplies a small, typically monochrome PNG icon (recommended around 72x72 or 96x96) shown in the Android status bar and shade, as distinct from the larger icon field used for the main notification image.
Read definitionbeforeinstallprompt
beforeinstallprompt is a window event Chromium browsers fire when a site meets the PWA install criteria. Capturing the event and calling prompt() later lets you show the install dialog at a moment of your choosing instead of at page load.
Read definitionbeforeinstallprompt userChoice
userChoice is a property on the deferred beforeinstallprompt event, resolving to an object like { outcome: "accepted" | "dismissed", platform: "web" }, available after calling deferredEvent.prompt(). It is the only reliable, synchronous-feeling signal for whether a user actually accepted or dismissed your custom install prompt in that specific interaction.
Read definitionCache Storage API
The Cache Storage API, exposed as the global caches object, lets a service worker (or page) store Request/Response pairs in named caches, e.g. caches.open("shell-v1").then((cache) => cache.put("/logo.png", response)). Unlike the HTTP cache, it is fully scriptable, has no automatic eviction schedule tied to headers, and persists until explicitly deleted or the storage quota is exceeded.
Read definitionCache-first strategy
Cache-first is a fetch-handling strategy: event.respondWith(caches.match(event.request).then((cached) => cached ?? fetch(event.request))). It serves cached content instantly and skips the network entirely when a match exists, making it ideal for versioned, immutable assets such as hashed JS/CSS bundles or app-shell icons that never change once deployed.
Read definitioncategories (manifest field)
categories is an optional manifest array, for example "categories": ["shopping", "business"], drawn loosely from a W3C-maintained list of common app-store category names. It has no effect on install eligibility or on-page behaviour and is purely metadata consumed by platforms that list PWAs alongside native apps.
Read definitionclients.claim()
self.clients.claim() is called inside the activate event of a service worker to make it start controlling every open page on the origin right away, rather than the default behaviour where a page keeps being controlled by whatever worker was active when it first loaded until the next navigation.
Read definitionDeclarative Web Push
Declarative Web Push is a format where the push message payload itself is a JSON object describing the notification (title, body, icon, and so on) that the browser displays directly, rather than requiring a service worker's push event handler to run arbitrary JavaScript to call showNotification(). WebKit introduced it partly to allow more efficient and more private push delivery on iOS/Safari.
Read definitiondisplay (manifest field)
display is the manifest field that chooses the browser chrome level for the installed app. Accepted values are fullscreen, standalone, minimal-ui and browser. "display": "standalone" is the most common choice because it hides the address bar and tab strip while keeping the OS status bar visible.
Read definitiondisplay_override (manifest field)
display_override is a manifest array, for example "display_override": ["window-controls-overlay", "standalone"], that lets a site opt into newer or experimental display modes such as window-controls-overlay on desktop, while still declaring a safe fallback. The browser walks the list in order and uses the first mode it understands.
Read definitiondisplay-mode media query
display-mode is a CSS media feature, usable both in stylesheets (@media (display-mode: standalone) { ... }) and in JavaScript via window.matchMedia("(display-mode: standalone)").matches, that reports which of browser, minimal-ui, standalone or fullscreen is currently applied to the page — regardless of what the manifest requested, since the OS can downgrade the requested mode.
Read definitionfetch event (service worker)
The fetch event fires in the service worker for every navigation, script, image or XHR request originating from a page it controls. Calling event.respondWith(promise) lets the worker substitute its own Response, most commonly by checking the Cache Storage API first and falling back to fetch() from the network.
Read definitionicons (manifest field)
icons is a manifest array of objects like {"src": "/icon-512.png", "sizes": "512x512", "type": "image/png"}. Chromium requires at least a 192x192 and a 512x512 PNG for install eligibility; the browser picks the closest size for each surface (home screen, splash screen, task switcher) rather than scaling a single image.
Read definitionid (manifest field)
id is a manifest field, for example "id": "/app-v1", used as the app's permanent identifier for the OS install registry. Unlike start_url, id is not meant to change; if it is omitted, the browser derives an identity from start_url instead, which means later changing start_url can register as a brand-new app.
Read definitioninstall event (service worker)
The install event fires on the ServiceWorkerGlobalScope the first time a browser registers a new or updated service worker script. Handlers typically call event.waitUntil(caches.open(...).then(cache => cache.addAll([...]))) to pre-cache the app shell before the worker is allowed to move to the "installed" state.
Read definitionLighthouse PWA audit
The Lighthouse PWA audit, run from Chrome DevTools' Lighthouse panel or the lighthouse CLI, checks a page against Chromium's installability criteria — valid manifest fields, icon sizes, registered service worker, HTTPS — and flags exactly which checks pass or fail, rather than giving a single opaque score for the category.
Read definitionMaskable icons
A maskable icon is declared with "purpose": "maskable" in the manifest icons array and must fill the entire square canvas with no transparent padding, keeping important content inside the central 80% "safe zone". Android then applies its own mask shape (circle, squircle, rounded square) on top without cutting off the logo.
Read definitionname (manifest field)
name is a required-in-practice string field in the Web App Manifest that gives the full, human-readable title of the app. Browsers show it on the install dialog, the splash screen and in the OS app switcher. It can be up to 45 characters before some UIs truncate it.
Read definitionNetwork-first strategy
Network-first is a fetch-handling strategy: event.respondWith(fetch(event.request).then((res) => { cache.put(event.request, res.clone()); return res; }).catch(() => caches.match(event.request))). It prioritises up-to-date data and only serves a cached copy if the network request fails outright, making it the standard choice for API calls and frequently changing pages.
Read definitionNotification permission states
Notification.permission returns one of three strings: "default" (the user has not yet decided, so the site may still call Notification.requestPermission() to ask), "granted" (the site may show notifications), or "denied" (the site is blocked from showing notifications and, critically, cannot re-prompt programmatically once denied).
Read definitionorientation (manifest field)
orientation is a manifest field, e.g. "orientation": "portrait-primary", that requests a fixed screen orientation for the installed app. Accepted values include any, natural, landscape, portrait, portrait-primary, portrait-secondary, landscape-primary and landscape-secondary.
Read definitionPrecaching
Precaching means fetching and storing a known list of build-time assets (HTML shell, CSS, JS bundles, key icons) in Cache Storage inside the install event handler, so they are guaranteed to be available offline from the very first load rather than being cached only after a user happens to request them.
Read definitionprotocol_handlers (manifest field)
protocol_handlers is a manifest array such as [{"protocol": "web+music", "url": "/play?track=%s"}] that registers the installed app as a handler for a URL scheme. Clicking a web+music: link anywhere in the OS, after the user confirms a one-time permission prompt, opens the app at the given URL with %s replaced by the encoded link.
Read definitionPush API
The Push API lets a service worker subscribe to a browser-run push service and receive encrypted messages from a server at any time, including when no tab or window for the site is open. Subscribing is done with registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey }), and incoming messages arrive in the worker's push event.
Read definitionpush event (service worker)
The push event fires on the service worker whenever a message arrives from the push service the browser is subscribed to. A handler typically reads event.data.json() for the payload and calls event.waitUntil(self.registration.showNotification(title, options)) so the browser keeps the worker alive until the notification is actually displayed.
Read definitionPushSubscription
A PushSubscription is the object returned by pushManager.subscribe(), containing an endpoint (a unique, vendor-hosted URL that identifies this specific device/browser installation) and a keys object with p256dh and auth values used to encrypt messages sent to it. Your server stores this per user and sends future notifications by POSTing an encrypted payload to subscription.endpoint.
Read definitionPWA install criteria
Chromium's PWA install criteria require: the site served over HTTPS; a linked Web App Manifest with at least a name (or short_name), a 192x192 and 512x512 icon, a start_url, and a display value of standalone, fullscreen, minimal-ui or a display_override entry; and a registered service worker with a fetch event handler, even a minimal pass-through one.
Read definitionRelated applications
related_applications is a manifest array such as [{"platform": "play", "id": "com.example.app"}] listing native app store equivalents of the PWA. The companion boolean field prefer_related_applications, when true, tells Chromium to prefer directing the user to install the native app instead of showing the web install prompt.
Read definitionrenotify (Notification option)
renotify is a boolean option, e.g. { tag: "order-42", renotify: true }, that only has an effect when combined with tag. Without renotify, a new notification that replaces an existing same-tag notification updates silently with no new sound or vibration; with renotify: true, the replacement alerts the user exactly as a brand-new notification would.
Read definitionrequireInteraction (Notification option)
requireInteraction is a boolean option, e.g. showNotification("Incoming call", { requireInteraction: true }), that prevents the browser from automatically dismissing the notification after its default timeout (a few seconds on most desktop platforms). The notification instead stays visible until the user clicks it, clicks an action, or closes it manually.
Read definitionRuntime caching
Runtime caching means storing a response in Cache Storage the first time a matching request is actually made by the user, inside the fetch event handler, as opposed to precaching, which loads a known asset list upfront during install. It is the natural fit for content whose full URL set is not known ahead of time, such as user-generated images or paginated API results.
Read definitionSafari share sheet install
On iOS, installing a PWA requires the user to manually tap the Share icon in Safari's toolbar, then choose "Add to Home Screen" from the resulting menu — there is no beforeinstallprompt equivalent, no browser-generated install banner, and no way for a site to trigger this flow programmatically.
Read definitionscope (manifest field)
scope is a manifest field, for example "scope": "/app/", that defines the URL prefix the browser considers part of the installed app. Navigating within scope keeps the app in standalone mode; navigating outside it (such as to an external payment page) typically opens a normal browser tab or an in-app browser bar.
Read definitionscreenshots (manifest field)
screenshots is a manifest array such as [{"src": "/shots/home.png", "sizes": "1080x1920", "type": "image/png", "form_factor": "narrow"}] used to render a richer install UI with app previews, similar to a Play Store listing, instead of the plain one-line install banner.
Read definitionService worker
A service worker is a JavaScript file the browser runs in the background, separate from the page. It intercepts network requests, caches responses so the site works offline, and receives web-push events so the site can notify the user when it is closed.
Read definitionService worker registration
Registration happens when a page calls navigator.serviceWorker.register("/sw.js", { scope: "/app/" }). The scope option (defaulting to the directory the script is served from) determines which pages the worker is allowed to control — a worker at /sw.js served with no scope option can normally only control /*, but serving it with the Service-Worker-Allowed HTTP header lets it claim a scope above its own script location.
Read definitionService worker update cycle
Browsers check a registered service worker's script for updates on every navigation to a page in scope, and at least every 24 hours in the background, by re-fetching the script URL and comparing it byte-for-byte against the currently installed version. Any difference — even a single changed character or comment — triggers a fresh install/waiting/activate cycle for a new worker instance.
Read definitionshare_target (manifest field)
share_target is a manifest object, for example {"action": "/share", "method": "POST", "enctype": "multipart/form-data", "params": {"title": "title", "text": "text", "url": "url", "files": [{"name": "media", "accept": ["image/*"]}]}}, that adds the installed PWA as a destination in the operating system's native share sheet.
Read definitionshort_name (manifest field)
short_name is an optional manifest string, typically under 12 characters, used wherever screen space is limited — the home-screen label, the app switcher, or a launcher grid. When short_name is absent the browser falls back to the full name field, which may get truncated with an ellipsis.
Read definitionshortcuts (manifest field)
shortcuts is a manifest array of up to (practically) four entries, each with name, url and optional icons, that appear when a user long-presses the installed app icon on Android or right-clicks it on Windows/ChromeOS. Example: {"name": "New order", "url": "/orders/new", "icons": [{"src": "/shortcut-new.png", "sizes": "96x96"}]}.
Read definitionsilent (Notification option)
silent is a boolean Notification option, e.g. showNotification("Synced", { silent: true }), that suppresses the sound, vibration and screen-wake behaviour a notification would normally trigger, while still adding it to the notification shade for the user to see whenever they next check.
Read definitionskipWaiting()
self.skipWaiting() is called inside a service worker's install (or activate) handler to skip the normal waiting state and activate immediately, even while older pages controlled by a previous worker are still open. It is usually paired with clients.claim() so the new worker also starts controlling those pages right away.
Read definitionStale-while-revalidate
Stale-while-revalidate is a fetch-handling strategy that serves whatever is already in Cache Storage without waiting on the network, then kicks off a background fetch to refresh that cache entry for the next request. It gives cache-first speed with eventual freshness, at the cost of occasionally showing content that is one request-cycle out of date.
Read definitionStandalone display mode
Standalone is a value of the display field in a Web App Manifest. It tells the browser to launch the PWA in its own window with no address bar or tabs, so it looks and behaves like a native app. It is the most common display mode for installable PWAs.
Read definitionStandalone mode detection
Standalone mode detection means checking, at runtime, whether the current page is running as an installed app rather than a regular tab. On Chromium and most browsers this is window.matchMedia("(display-mode: standalone)").matches; on iOS Safari the historical equivalent is the non-standard navigator.standalone boolean, since iOS predates the display-mode media feature's adoption there.
Read definitionstart_url (manifest field)
start_url is the manifest field that sets the exact URL loaded when a user taps the installed app icon. It is resolved relative to the manifest URL, so "start_url": "/?source=pwa" launches the origin root with a query string you can use to distinguish installed-app sessions from browser-tab sessions in analytics.
Read definitiontag (Notification option)
tag is a string option, e.g. showNotification("New message", { tag: "chat-thread-42" }), used to identify a class of related notifications. When a new notification arrives with a tag matching one already showing, the browser replaces it in place by default rather than adding a second, separate notification to the shade.
Read definitiontheme_color (manifest field)
theme_color is a manifest field, e.g. "theme_color": "#0f172a", that tints the Android status bar, the task-switcher card header and, on some platforms, the browser toolbar while the site is open. It accepts any valid CSS colour value.
Read definitionVAPID
VAPID (Voluntary Application Server Identification) is a key-pair scheme, standardised in RFC 8292, where a server generates one ECDSA P-256 key pair, keeps the private key secret, and shares the public key with browsers via the applicationServerKey option when subscribing. It lets push services verify which application server is sending a given message without requiring a proprietary developer account per browser vendor.
Read definitionwaiting state (service worker)
A service worker enters the waiting state after install succeeds but before it can activate, because the browser only replaces an active worker once every page it currently controls has been closed or navigated away from. It stays here indefinitely until those pages close or the code forces the transition with skipWaiting().
Read definitionWeb App Manifest
A Web App Manifest is a JSON file (usually manifest.webmanifest) that declares your app's name, icons, start URL, theme colour and display mode. The browser reads it to render the install prompt and the home-screen icon.
Read definitionWeb push
Web push is a W3C standard that lets a website deliver push notifications to a user's device via the browser's push service, even when the site is closed. Delivery requires a service worker and explicit user permission.
Read definitionWebAPK
A WebAPK is a small, real Android application package that Chrome generates and signs on the fly (via a Google-run server) when a user installs a qualifying PWA on Android. It gives the installed site a genuine entry in Android Settings > Apps, its own task-switcher identity separate from Chrome, and the ability to be the registered handler for its own scope's URLs.
Read definitionWorkbox
Workbox is a collection of JavaScript libraries and build tools (workbox-precaching, workbox-routing, workbox-strategies, workbox-expiration, and more) maintained by the Chrome team that implement the recurring service worker patterns — precache manifests, route matching, cache-first/network-first/stale-while-revalidate strategies — so teams do not hand-roll them from scratch.
Read definition