Glossary
Web app manifest
A web app manifest is a JSON file a page links to, declaring how the site should behave when installed to a device: its name, its icons, how it launches, and which URL it opens. Its defining characteristic in practice is silent failure — a manifest can be served, valid and read, and the install prompt simply never appears, with nothing in the interface or the console naming the field that was missing.
What it declares
A full name and a short name, the second being what fits under an icon on a home screen.
Icons at several sizes, including a maskable variant so an operating system applying its own shape does not crop into the artwork.
A display mode deciding whether the installed entry opens in a browser tab, a standalone window or full screen.
A start URL and a scope, which together say what belongs to the installed application and what should open in a browser instead.
Theme and background colours, which are what make the launch look like an application rather than a page loading.
Why the failure is silent
The install prompt is offered when a browser's own conditions are met, and when one is not, nothing reports which.
A missing icon at a required size is the usual cause and the least visible: the manifest is valid and the declared icons work everywhere else.
A missing display mode is next, because a manifest without one falls back to a mode the browser does not treat as installable.
Conditions also differ between browsers and change over time, so a manifest that worked can stop working without being edited.
Which is why listing the recommended fields that are absent is the closest thing to an explanation available.
What else installability requires
The site must be served over HTTPS, which is a prerequisite rather than a manifest field.
Some platforms require a service worker to be registered, which is a separate piece of machinery entirely.
The start URL must be within the declared scope, and a mismatch there breaks the launch rather than the prompt.
Moving a site to a subdirectory or a new hostname breaks the start URL and the scope together, which is a common cause after a migration.
When it is worth having at all
When the site is genuinely something people return to and would benefit from launching directly.
Not on a brochure site or a content site people arrive at from search, where an install prompt is an interruption offering nothing.
A missing manifest is therefore not a defect, and its absence is reported as absence.
The icon and theme colour declarations have modest value even without installability, since some platforms use them elsewhere.
How it is observed
A manifest declared by the pages is detected and fetched once per scan.
The served file is parsed and the recommended fields that are missing are listed, which is the actionable output.
Declared icons are not fetched, so an icon declared at a size it is not really rendered at is not caught.
Service worker registration is outside this, and so are the browser-specific install criteria that change over time.
Frequently asked questions
- My manifest is valid but no install prompt appears. Why?
- Most often a missing icon at a size the platform requires, or a missing display mode. The file stays valid, the prompt is not offered, and the browser gives no reason.
- Does every site need one?
- No. It makes a site installable to a home screen, which is valuable for something people return to and an interruption on a site people arrive at from search.
- What is a maskable icon?
- A variant with enough safe margin that an operating system applying its own shape does not cut into the artwork — which is why a normal icon often looks wrong once installed.
Sources
Related
VeriFixScan crawls a site and applies its checks to every page it reaches, keeping the evidence behind each finding. Scanning one website is free.
Scan a website