Web app manifest

The fields that actually matter

A manifest is short, and most of it is metadata the operating system reads once at install time:

• name and short_name — the full name and the one that fits under a home screen icon.
• icons — an array of sources with sizes. 192×192 and 512×512 are the practical minimum; purpose: "maskable" lets Android crop the icon into its own shape without cutting off your logo.
• start_url — the address the app opens at, which does not have to be the page the user installed from.
• display — standalone removes the browser address bar, browser keeps it, fullscreen hides everything.
• theme_color and background_color — the system UI tint and the colour shown during launch, before the first paint.

Published NorthernGo apps are served a generated /manifest.json with display: "standalone" and a maskable icon, so the app opens from its own icon rather than inside a tab.

Where it goes wrong

Three failure modes cover almost everything.

Icons that look broken after install. Android applies its own mask, so a square logo with content at the edges gets clipped. Building the icon with a safe margin, or shipping a separate maskable version, is the fix — see the app icon guide.

A start_url outside the scope. If the start address falls outside the manifest scope, the app opens in a normal browser tab and the install looks half-broken.

Expecting the manifest to do more than it does. This is the common misconception: a manifest makes an app installable, not offline-capable and not faster. Everything about working without a connection lives in the service worker. A site with a perfect manifest and no service worker installs beautifully and then shows a blank screen on a train.

The manifest is also read at install time, so changing an icon or a name does not update apps that are already on someone's home screen until they reinstall.