manifest.webmanifest: every field, ranked by impact

The Web App Manifest is a JSON file the browser reads to decide whether — and how — to install your site. It has 30+ fields. Seven of them do 90% of the work; the rest are for specific platforms. Here’s the honest ranking.

Required for install

{
  "name": "Long name shown on install prompt",
  "short_name": "Home-screen label (≤12 chars)",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#111827",
  "icons": [
    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any maskable" }
  ]
}

Omit purpose: "any maskable" on the 512 icon and Android install will silently fail on Pixel devices.

High-value optional

• scope — controls which URLs open inside the installed app vs bounce to the browser.
• display_override — array of preferred display modes. Use ["window-controls-overlay", "standalone"] for desktop apps that want title-bar customisation.
• shortcuts — right-click jump-list items on Android, Windows, ChromeOS.
• screenshots — richer install UI on Chrome Android and the Play Store TWA listing. Provide 540×1080 and 1080×1920.
• id — pin your PWA identity. Without it, changing start_url breaks the install matching and the browser treats you as a new app.

Sometimes-useful

share_target registers your PWA as a share destination. protocol_handlers lets you claim custom schemes like web+mytool://. file_handlers associates file types.

Quietly ignored today

related_applications and prefer_related_applications — useful only if you also ship a native app and want to divert installs.

Validation

Serve the file as application/manifest+json (or application/json). Link it from every page: <link rel="manifest" href="/manifest.webmanifest">. Use Chrome DevTools → Application → Manifest to see the parsed result.

The three fields we see broken most often

1. start_url pointing to a URL that 404s when the service worker isn’t installed.
2. Icons with the wrong MIME type (server returns text/plain).
3. scope narrower than start_url, which invalidates the manifest silently.

Use the free manifest generator if you’d rather skip the JSON.