Manifest Basics

The essential manifest fields

A minimal manifest must have enough information for the browser to install the app and display it correctly. The table below lists the most important fields:

Field	Required	Purpose
`name`	Yes	Full app name shown in install prompts and the app launcher
`short_name`	Recommended	Truncated name for home screens with limited space
`start_url`	Yes	URL the app opens when launched from the home screen
`scope`	Recommended	URL prefix that defines which pages are “inside” the app
`id`	Recommended	Stable identifier; prevents duplicate installs across URL changes
`description`	Recommended	Short blurb shown in app stores and install UI
`lang`	Recommended	Primary language of the manifest content (e.g. `"en"`)
`dir`	Recommended	Text direction: `"ltr"`, `"rtl"`, or `"auto"`

A full example

{
  "name": "My Awesome PWA",
  "short_name": "AwesomePWA",
  "id": "/",
  "start_url": "/",
  "scope": "/",
  "description": "A fast, offline-capable progressive web app.",
  "lang": "en",
  "dir": "ltr",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#5A0FC8",
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

Field details

name vs short_name — name is displayed in the install dialog and splash screen. short_name is used on the home screen where space is tight (Android typically truncates at around 12 characters). If short_name is omitted, the browser falls back to name.

start_url — This is where the app navigates to when a user taps its icon. Use "/" to start at the root. You can also append query params to track installs: "/?source=pwa".

scope — Any navigation outside the scope forces the browser to open a regular browser tab instead of staying in the standalone window. Keep scope equal to "/" for single-origin apps, or narrow it to a sub-path like "/app/" if your marketing pages should stay outside the PWA shell.

id — A stable string that uniquely identifies the app. If you later change start_url, the browser will not create a duplicate install as long as id stays the same. Set it to "/" or a permanent URL path.

lang and dir — These tell assistive technology and the OS which language and text direction to use for the app’s name and description.

Try it live

The playground below serves a minimal manifest. Open it in StackBlitz and check the DevTools Application → Manifest panel to verify every field is parsed correctly.

Runs a real service worker + manifest in your browser.

Trade-offs

Option	Benefit	Cost
Fill in every field the spec recommends (name, icons, start_url, display)	Passes every browser’s installability criteria immediately	Requires preparing multiple icon sizes and testing them all before shipping
Fill in only the bare minimum fields that make the build pass	Fast to get started, does not block development	Lighthouse-era installability checks may not fully pass — you have to come back and fix it later

Common mistakes

Setting start_url to a relative path that does not resolve from the root, so opening the app from the home screen lands on an unintended page.
Forgetting short_name, so the label under the home-screen icon gets truncated into something unreadable.
Linking the manifest with the wrong MIME type or path, so the browser cannot find it and the app is never considered installable.

Squoosh — Google Chrome Labs’ open-source image-compression PWA — ships a manifest with every required field filled in from the start (source on GitHub), which is a good example to model a real manifest on beyond this lesson’s demo.