Web App Manifest: Complete Guide

Introduction to Web App Manifest

The Web App Manifest is a foundational technology for Progressive Web Apps (PWAs). It provides a standardized, JSON-based text file that allows developers to control how their web application appears to users in areas where they would normally expect to see native applications, such as the device's home screen or app launcher.

What is a Web App Manifest?

At its core, a Web App Manifest is simply a JSON file named (by convention) manifest.json or manifest.webmanifest. It contains metadata about the web application, including its name, icons, start URL, display mode, and theme colors. When a browser reads this file, it unlocks native-like capabilities for the web app, most notably the ability to be "installed" on a user's device without going through an app store.

Why Does It Matter?

Without a manifest, a web app is just a browser tab. With a manifest, the web app bridges the gap between web and native. Here is why it matters:

Installability: It satisfies a core requirement for browsers to show the "Add to Home Screen" prompt, allowing users to install the PWA directly.
Native Experience: It allows the app to launch in a standalone window without browser UI elements (like the address bar), making it feel like a native app.
Branding: Developers can define custom splash screens, app icons, and theme colors that integrate seamlessly with the host operating system's UI.
Engagement: Installed PWAs typically see higher user engagement and retention rates compared to standard bookmarked websites.

Creating Your First Web App Manifest

Creating a manifest is straightforward. You define a JSON object with specific properties and then link it in your HTML document.

Basic Structure

Here is a basic example of a manifest.json file:

{
  "name": "My Awesome App",
  "short_name": "AwesomeApp",
  "description": "A demonstration of a Progressive Web App manifest.",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#1976d2",
  "icons": [
    {
      "src": "icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

Linking the Manifest to Your HTML

Once you have created your manifest file, you must link it to your web pages using the <link> tag inside the <head> of your HTML document.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Awesome App</title>
  
  <!-- Link to the Web App Manifest -->
  <link rel="manifest" href="/manifest.json">
  
  <!-- Link to theme color for browser UI integration -->
  <meta name="theme-color" content="#1976d2">
</head>
<body>
  <h1>Welcome to My Awesome App</h1>
</body>
</html>

Key Manifest Properties Explained

To get the most out of your Web App Manifest, you need to understand the various properties available.

Identity and Presentation

name: The full name of the application, used in the app launcher or install prompt.
short_name: A shorter version of the name, used on the home screen where space is limited.
description: A brief explanation of what the app does, often shown in install prompts.
start_url: The relative or absolute URL that loads when the app is launched from an icon.
display: Defines the display mode. Options include fullscreen (no UI), standalone (looks like a native app), minimal-ui (some browser UI), and browser (standard browser tab).
orientation: Sets the default screen orientation (e.g., portrait or landscape).

Icons and Splash Screens

The icons array is critical. Browsers require at least a 192x192 and a 512x512 icon to allow installation. When the app launches, the OS uses the background_color and the largest available icon to generate a splash screen automatically.

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

The purpose field tells the OS how to use the icon. any means it can be used anywhere, while maskable indicates the icon is designed with a safe zone so the OS can mask it into shapes like circles or squircles.

App Behavior and Navigation

scope: Defines the navigation scope of the web application. If the user navigates outside this scope, the app will open in a standard browser window.
theme_color: The primary color of the app, used to tint the OS UI elements (like the status bar on Android).
background_color: The color displayed before the stylesheet loads, preventing a flash of white.

Advanced Features

The manifest specification includes advanced properties that can further enhance the native feel of your PWA.

Shortcuts

You can define app shortcuts that appear when a user long-presses or right-clicks the app icon. This is excellent for deep linking to specific features.

"shortcuts": [
  {
    "name": "New Message",
    "short_name": "New",
    "description": "Open the new message composer",
    "url": "/messages/new",
    "icons": [{ "src": "/icons/new-message.png", "sizes": "96x96" }]
  },
  {
    "name": "Settings",
    "short_name": "Settings",
    "url": "/settings"
  }
]

Screenshots

To make your install prompt more compelling, you can provide screenshots. These are displayed in rich install UI on desktop and mobile platforms.

"screenshots": [
  {
    "src": "screenshots/dashboard.png",
    "sizes": "1280x720",
    "type": "image/png",
    "platform": "wide",
    "label": "Dashboard View"
  },
  {
    "src": "screenshots/mobile-profile.png",
    "sizes": "390x844",
    "type": "image/png",
    "platform": "narrow",
    "label": "User Profile"
  }
]

Best Practices

To ensure your Web App Manifest works flawlessly across all platforms, follow these best practices:

Always use maskable icons: Provide at least one icon with "purpose": "maskable" to ensure your icon looks good on Android devices that enforce circular or custom shapes.
Provide multiple icon sizes: Do not rely solely on 192px and 512px icons. Include smaller sizes (e.g., 72x72, 96x96) for favicons and notifications.
Keep the start_url relative: Use "/" or "./index.html" instead of absolute URLs to ensure the app works correctly regardless of the domain it is hosted on.
Test in DevTools: Use the Application tab in Chrome or Edge Developer Tools to inspect your manifest, verify icons are loading, and test the install prompt.
Set a theme-color meta tag: Always include <meta name="theme-color" content="#yourcolor"> in your HTML head to match your manifest's theme_color for older browsers and broader OS support.
Include a service worker: A manifest alone makes an installable web app, but pairing it with a service worker ensures it works offline, making it a true PWA.

Conclusion

The Web App Manifest is a powerful, lightweight tool that transforms a standard website into an installable, native-like application. By carefully defining your app's identity, icons, and display preferences, you can significantly improve user experience and engagement. While the JSON structure is simple, the impact it has on how users interact with your web app is profound. By following the best practices outlined in this guide and testing thoroughly across devices, you can ensure your Progressive Web App delivers a seamless, high-quality experience that rivals native applications.