PWA: Manifest, Install, Push, and Background Sync

## What the manifest is A web app manifest is a JSON document, served with the media type `application/manifest+json`, that tells the browser how to present a site when it is installed as an app. The document references it, and the browser fetches it when it evaluates installability or when the user installs. It changes nothing about how the page renders in an ordinary tab — a manifest with a typo does not break the site, it just quietly stops the install from working. ## Identity: name, short_name, id `name` is the full application name shown in the install dialog and app lists. `short_name` is the truncated label shown under a home-screen icon, so it should be a handful of characters. `id` is an explicit identity string for the app. Without it, the browser derives identity from `start_url`, which means that changing the launch URL later can be interpreted as a *different* app and produce a duplicate install rather than an update. Setting `id` once (`"id": "/?app"`, for example) makes identity independent of the launch URL. ## Launch and boundaries: start_url and scope `start_url` is resolved relative to the manifest's own URL and is what opens when the icon is tapped. Teams frequently add a marker query — `"start_url": "/?source=pwa"` — so analytics can separate launches from ordinary web traffic. `scope` is a URL prefix defining what counts as "inside" the app. Navigations within scope stay in the app window; a navigation outside it (an external link, a payment provider, an auth redirect on another origin) is handed to the browser, typically as an in-app browser view. If `scope` is omitted it defaults to `start_url` with its last path segment removed, which is why an app whose `start_url` is `/app/index.html` and whose real routes live at `/` can mysteriously bounce users out to a browser tab. ## Presentation: display, theme_color, background_color `display` takes one of four values, and the browser falls back down the list if it cannot honour the one you asked for: - `fullscreen` — no browser UI and no system UI where the platform allows it. - `standalone` — its own window, app title bar, no URL bar. - `minimal-ui` — standalone plus a minimal set of navigation controls. - `browser` — a normal tab; Chromium also treats this as not installable. `display_override` is an ordered array consulted before `display`, and is how you opt into newer modes such as `"window-controls-overlay"` while keeping `standalone` as the fallback. `theme_color` tints the app's title bar and the OS task-switcher entry; `background_color` paints the launch screen in the moment between tapping the icon and your first paint, so it should match your app's real background or users see a flash. In script you can detect the mode you were launched in: ```js const installed = window.matchMedia('(display-mode: standalone)').matches; ``` ## Icons `icons` is an array of objects with `src`, `sizes` (`"192x192"`, or `"any"` for SVG), `type`, and `purpose`. `purpose: "any"` is the default; `purpose: "maskable"` marks an icon drawn with a safe zone so Android can crop it into whatever shape the launcher uses — without one, an adaptive launcher may clip your logo. `purpose: "monochrome"` supplies a single-colour variant for badging. ## What the manifest does not do The manifest is metadata only. It does not cache anything, does not make the app work offline, and does not intercept requests — those are jobs for a service worker. Nor is any of it required for the site to function; a site without a manifest is simply a site that cannot be installed as an app. ## Debugging Browser devtools expose the parsed manifest, so the fastest check is to open the application panel and look at what the browser actually resolved: a manifest fetched with the wrong content type, blocked by an auth gate, or containing trailing-comma JSON produces an empty panel rather than an error in the console.