Web App Manifest Audit — Score Your PWA Install-Readine...

A web app manifest is a JSON file that tells the browser how your site should behave when a user installs it to their home screen. It controls the app name, the icon, the splash screen color, the display mode, and the start URL. Without it, your site cannot be installed as a Progressive Web App.

The problem is that most manifests are either missing entirely, incomplete, or filled with fields that do not meet current browser requirements. A manifest audit catches these gaps before your users hit an install button that does nothing.

What the audit checks

A manifest audit fetches your manifest.json (or manifest.webmanifest) and scores it against two tiers of fields:

Required fields that browsers check before showing an install prompt:

name or short_name — what appears under the icon on the home screen. Both should be present. short_name gets used when space is tight, so keep it under 12 characters.
start_url — where the app opens when launched. This should be a clean URL, not a page with query parameters from your analytics.
display — how the app looks when running. standalone removes the browser chrome. fullscreen removes everything. minimal-ui keeps a small navigation bar. browser is the default and does not trigger install prompts on most platforms.
icons — at minimum, you need a 192x192 and a 512x512 PNG icon. Without both sizes, Chrome will not show the install prompt.

Recommended fields that improve the installed experience:

theme_color — controls the status bar and title bar color on mobile and desktop.
background_color — sets the splash screen color while the app loads. Without it, users see a white flash before your app paints.
description — shows in app stores and install dialogs on some platforms.
scope — defines which URLs belong to your app. Navigating outside the scope opens the system browser.
screenshots — used by some browsers to show a richer install dialog.
categories — helps with app store discoverability on platforms that support it.

Missing a required field means the install prompt will not appear. Missing recommended fields means the installed app looks unfinished.

Why manifests break silently

The frustrating thing about manifest problems is that they fail quietly. There is no error message when your install prompt does not show up. The browser just decides your site does not qualify and moves on. Users never see the option to install.

This is especially painful if you have already built service worker caching, offline support, and push notifications. All that work becomes invisible if the manifest is incomplete, because installability is the gateway to the rest of the PWA feature set.

Common failures include:

Wrong icon sizes: You have a 144x144 icon but not a 192x192. Close does not count.
Missing start_url: The browser does not know where to send users when they tap the icon.
display: browser: This is the default and explicitly tells the browser not to offer installation.
Invalid JSON: A trailing comma or unquoted key silently breaks the entire manifest. The browser ignores it without warning.
Wrong MIME type: Your server sends manifest.json with text/html instead of application/manifest+json. Some browsers tolerate this. Others do not.

The business case for installability

Installed PWAs get used more than bookmarked websites. They sit on the home screen next to native apps. They show up in the app switcher. They can receive push notifications. On Android, they appear in the app drawer and the share sheet.

For small businesses especially, a PWA can replace a native app that would cost tens of thousands of dollars to build and maintain. The manifest is the cheapest part of the stack, and it is the part most often done wrong.

Search engines also factor PWA signals into mobile rankings. A complete manifest with proper icons and display mode contributes to the overall technical quality signal that affects how your pages rank on mobile devices.

Running the audit

The Web App Manifest Audit tool fetches your manifest, parses it, and scores every required and recommended field. It flags missing icons, invalid display modes, and fields that would prevent installation. The fix prompt gives you a complete, corrected manifest you can drop into your project.

If you are building sites for clients and want to understand how PWA installability fits into a broader monetization strategy, the Digital Empire Series covers the practical economics of web apps that work offline and stay on the home screen.

Fact-check notes and sources

Chrome requires name (or short_name), start_url, display (not browser), and icons at 192x192 and 512x512 to trigger the install prompt. These requirements are documented in Chrome's web.dev PWA documentation.
Safari on iOS added home screen web app support with manifest.webmanifest in Safari 17 (September 2023), though with more limited feature support than Chrome.
The maskable icon purpose, which ensures icons display correctly in adaptive icon shapes on Android, was added to the spec in 2020.
Firefox removed its PWA install support on desktop in January 2024 but retains it on Android.

Why a Web App Manifest Audit Matters for PWA Installability