Web Manifests: The Key to PWAs Success

The Web Manifest is a simple JSON file that provides metadata about a web app, including essential information for web apps to behave like native apps on mobile devices.

The primary benefit of Web Manifest is that it allows web apps to be installed on a user’s device and accessed from the home screen or app drawer, just like native apps. This improves the user experience by reducing the friction of launching a web app and providing a more immersive experience that feels like a native app.

Web Manifest is primarily used for Progressive Web Applications (PWAs). However, it can also be used to provide metadata for regular web pages, may be used by search engines or other tools to enhance the user experience.

The specification

Here’s the Web Manifest specification format, maintained by the W3C, with all the fields and their descriptions added as comments directly on the JSON. Each field has a specific data type and format, and some fields are required while others are optional.

{
  // Name of the web application (required).
  "name": "Example App",
  
  // Short name of the web application (required).
  "short_name": "Example",
  
  // Description of the web application.
  "description": "An example progressive web application.",
  
  // URL to the start page of the web application (required).
  "start_url": "/",
  
  // Display mode of the web application (e.g. "fullscreen", "standalone", "minimal-ui", "browser").
  "display": "standalone",
  
  // Orientation mode of the web application (e.g. "any", "natural", "landscape", "portrait", "portrait-primary", "portrait-secondary", "landscape-primary", "landscape-secondary").
  "orientation": "any",
  
  // Language of the web application (e.g. "en-US", "en", "fr-FR", "fr").
  "lang": "en-US",
  
  // Direction of the text in the web application (e.g. "ltr", "rtl").
  "dir": "ltr",
  
  // Background color of the web application.
  "background_color": "#f5f5f5",
  
  // Theme color of the web application.
  "theme_color": "#4285f4",
  
  // List of icons for the web application.
  "icons": [
    {
      // URL to the icon (required).
      "src": "icon-72x72.png",
      
      // MIME type of the icon (required).
      "type": "image/png",
      
      // Size of the icon in pixels (optional).
      "sizes": "72x72"
    },
    {
      "src": "icon-96x96.png",
      "type": "image/png",
      "sizes": "96x96"
    },
    {
      "src": "icon-128x128.png",
      "type": "image/png",
      "sizes": "128x128"
    },
    {
      "src": "icon-144x144.png",
      "type": "image/png",
      "sizes": "144x144"
    },
    {
      "src": "icon-192x192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "icon-256x256.png",
      "type": "image/png",
      "sizes": "256x256"
    },
    {
      "src": "icon-384x384.png",
      "type": "image/png",
      "sizes": "384x384"
    },
    {
      "src": "icon-512x512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  
  // List of related applications for the web application.
  "related_applications": [
    {
      // Platform for the related application (e.g. "play", "itunes", "windows").
      "platform": "play",
      
      // URL to the related application (required).
      "url": "https://play.google.com/store/apps/details?id=com.example.app"
    }
  ],
  
  // List of shortcuts for the web application.
  "shortcuts": [
    {
      // Name of the shortcut (required).
      "name": "Example Shortcut",
      
      // Description of the shortcut.
      "description": "An example shortcut.",
      
      // URL to the shortcut (required).
      "url": "/",
      
      // List of icons
       "icons": [
        {
          // URL to the icon (required).
          "src": "shortcut-icon-48x48.png",
          
          // MIME type of the icon (required).
          "type": "image/png",
          
          // Size of the icon in pixels (optional).
          "sizes": "48x48"
        }
      ]
    }
  ],

  // List of categories for the web application.
  "categories": [
    "example",
    "pwa"
  ],

  // Scope of the web application (e.g. "/myapp/").
  "scope": "/",

  // Prefer related applications over the web application when installed (e.g. true or false).
  "prefer_related_applications": false,

  // Display the web application as a splash screen when launched from the home screen (e.g. "auto", "browser", "standalone", "fullscreen").
  "splash_pages": {
    "tablet": "/tablet-splash.html",
    "phone": "/phone-splash.html"
  },

  // Default theme color for the web application (deprecated).
  "default_theme_color": "#4285f4"
}

I included comments in the example to provide a clear and concise explanation of each field and its purpose. However, comments are not allowed in JSON syntax and should be removed before using the file in your own web application.

File extension .webmanifest or .json?

The file extension for a web manifest can be either .webmanifest or .json. Both extensions are recognized by modern browsers. Regardless of the extension used, the file must contain valid JSON syntax and follow the web manifest specification to be recognized by the browser.

The .webmanifest extension is recommended by the W3C specification and is the more commonly used extension for web manifests, along with application manifest media type (application/manifest+json), both registered by Internet Assigned Numbers Authority (IANA).

However, some developers may prefer to use the .json extension for consistency with other JSON files in their project, or not at all (e.g. /api/GetManifest), but are encouraged to transfer the manifest using the application/manifest+json MIME type, although any JSON MIME type is ok.

Linking to a manifest

In many cases, your web manifest file will be generated and linked automatically as part of your build process and placed in the same directory as your HTML index file. This is often the default behavior for modern frameworks.

To manually link a web manifest file in your HTML code, you can use the link tag in <head> section with the rel attribute set to “manifest”. The href attribute should point to the location of the web manifest file. Here’s an example:

<!DOCTYPE html>
<html>
  <head>
    <title>byby</title>

    <!-- Startup configuration -->
    <link rel="manifest" href="manifest.webmanifest">

    <!-- Fallback application metadata for legacy browsers -->
    <meta name="application-name" content="byby">
    <link rel="icon" sizes="16x16 32x32 48x48" href="lo_def.ico">
    <link rel="icon" sizes="512x512" href="hi_def.png">
  </head>
  <body>
    <!-- your page content here -->
  </body>
</html>

Regardless of the location of your web manifest file, you will need to ensure that the manifest file is correctly linked to your HTML index file. The browser will automatically detect and parse the web manifest file when the page is loaded, allowing it to apply the specified settings to the web application.

Browser compatibility

The Web Manifest is supported by most modern browsers on desktop and mobile platforms. Here’s a list of major browsers and the versions at which they began to support Web Manifest:

• Google Chrome: version 39+
• Mozilla Firefox: version 47+
• Apple Safari: version 11.1+
• Microsoft Edge: version 17+
• Opera: version 26+

The support for some of the Web Manifest fields and options may vary across browsers and versions. For example, some browsers may not support the related_applications field, while others may not support the shortcuts field. It’s important to test your Web Manifest across multiple browsers and versions to ensure that it works as expected.

Some older browsers may not support the Web Manifest at all. In these cases, the web application will still work, but it may not have the same functionality as a fully-installed progressive web application.

Conclusion

One additional thing to note about web manifests is that they can be updated over time as the web application evolves. If you make changes to your web application, you may need to update the web manifest to reflect those changes.

It’s also worth noting that while web manifests are not required for all web applications, they can provide significant benefits for PWAs. By including a web manifest, you can improve the user experience and engagement of your web application, making it more competitive with native mobile applications.