PWA manifest icons: a complete checklist

Check each icon entry

Verify that every `src` resolves, declared `sizes` match the actual image, and `type` describes the file format. Follow current browser guidance for the set of icons needed by your supported install surfaces.

Set purpose intentionally

Use the manifest `purpose` field according to the icon’s role, such as `any` or `maskable`. A maskable icon should fill its intended safe area so a browser or launcher can apply a shape without cutting off the subject.

Review theme and background colors

Choose `theme_color` and `background_color` values that fit the site and the icon. Check the result in browser chrome and during installation, where supported, rather than relying on a color swatch alone.

Test installability and cache updates

Use browser developer tools to inspect manifest errors and confirm the page meets the current installation criteria. After changing icon files, verify the deployed paths and account for service-worker or browser caching.

Preview every icon on real backgrounds

Check the icon at small sizes and against light, dark, and masked surfaces. Keep important details away from crop boundaries and make sure the PWA icon is not confused with an unrelated store listing asset.

Inspect the manifest as deployed

Open the production manifest from the page that declares it and resolve each icon path relative to the manifest URL. A path that works from the site root may fail when the manifest lives in a subdirectory.

Check that declared dimensions match the actual image and that the MIME type is correct. Use browser developer tools to inspect parse errors and confirm the installed app uses the current manifest after deployment.

Review maskable artwork in a mask preview

A maskable image should place its key mark inside the safe region while allowing the background to extend to the canvas edge. Preview circular, rounded, and other supported masks so a launcher does not cut off the symbol.

Keep an `any` icon when you need an unmasked version as well. Choose manifest purposes deliberately and confirm the result on the browsers and operating systems you support.

Example manifest checks

For each entry, verify `src`, `sizes`, and `type` against the file on the deployed server. Add `purpose` when an icon is intended for maskable use, and keep an ordinary icon entry when an unmasked rendering is also needed.

Do not declare a size the image does not contain. If a source file includes multiple sizes, list the dimensions it actually provides and confirm the browser can fetch the path from the manifest location.

Test an installed update

After updating icons, reinstall or refresh the PWA on representative browsers to check whether the new assets are picked up. Manifest and service-worker caches can make the installed icon look older than the deployed source.

Test the start URL, scope, theme colors, and icon together. A valid icon manifest is only one part of an installable and coherent launch experience.

Check paths, scope, and deployment base

Resolve `src` values relative to the manifest location and confirm they work under the production base path. Local development at `/` can hide a broken icon path when the app is deployed under a subpath.

Check the manifest response, not only the file in source control. A stale service worker or an incorrect content type can keep the browser from seeing the updated icon set.