Web App Manifest

The Web App Manifest is a critical component of Progressive Web Apps (PWAs), enabling installability, app-like behavior, and consistent branding across browsers. It's a JSON file that defines metadata such as the app's name, icons, theme colors, and display mode. Proper configuration ensures users can install your PWA, launch it as a standalone app, and enjoy features like offline access and push notifications.

Manifest Structure and Key Properties¶

The manifest file (manifest.json) must include the following core properties:

1. Basic Metadata¶

{
  "name": "My PWA App",
  "short_name": "PWA",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#007bff"
}

- name: Full name of the app (displayed in the OS install prompt). - short_name: Abbreviated name for smaller screens (e.g., home screen). - start_url: URL to open when the app is launched. - display: Controls how the app is presented (standalone, minimal-ui, fullscreen, etc.). - background_color/theme_color: Colors for the app's UI and browser UI.

2. Icons¶

"icons": [
  {
    "src": "/icon-192x192.png",
    "sizes": "192x192",
    "type": "image/png"
  },
  {
    "src": "/icon-512x512.png",
    "sizes": "512x512",
    "type": "image/png"
  }
]

- Provide multiple icon sizes (e.g., 192x192, 512x512) for different devices. - Include web app icons (square, no transparency) and maskable icons for full-screen use.

3. Scope and Other Properties¶

"scope": "/",
"orientation": "any",
"prefer_related_applications": false,
"related_applications": []

- scope: Limits the app's installable area (e.g., / for the root). - orientation: Restricts the app's orientation (any, natural, landscape, etc.). - related_applications: Links to native app stores (optional).

Registering the Manifest¶

To register the manifest, add a <link> tag to your HTML file:

<link rel="manifest" href="/manifest.json">

Ensure the manifest is served with the correct MIME type (application/json) and is accessible via a CORS-enabled endpoint. For example:

curl -I https://yourdomain.com/manifest.json
# Should return: Content-Type: application/json

Testing and Validation¶

Chrome DevTools:
Open DevTools → "Application" tab → "Manifest" section.
Check for errors (e.g., missing icons, invalid URLs).
Use the "Install" prompt to simulate the user experience.
Lighthouse Audit: Run a Lighthouse audit to verify PWA compliance:
```
lighthouse https://yourdomain.com --quiet
```
Look for "Installable" and "Manifest" scores.
Cross-Browser Testing:
Test on Chrome, Firefox, and Edge (support varies).
Use tools like Web App Manifest Validator for syntax checks.

Common Pitfalls and Best Practices¶

Missing Icons: Ensure all required icon sizes are present.
Incorrect Manifest URL: The href must match the actual file location.
Scope Conflicts: Avoid overly restrictive scope values that limit functionality.
Dynamic Updates: Use skipWaiting and clients claim in service workers to update the manifest.

Key takeaways¶

The manifest defines metadata for installability, branding, and display behavior.
Include multiple icon sizes and types for compatibility.
Register the manifest via <link> and validate its CORS settings.
Test with Lighthouse and browser DevTools to ensure PWA compliance.
Prioritize standalone display mode and valid start_url for a seamless user experience.