Skip to content

Web App Manifest — Make Your PWA Installable

DodaTech Updated 2026-06-28 6 min read

In this tutorial, you will learn about Web App Manifest. We cover key concepts, practical examples, and best practices to help you master this topic.

The web app manifest is a JSON file that controls how your PWA appears when installed — name, icons, theme color, display mode, and start URL — telling the browser how your app should behave on the user's device.

What You'll Learn

By the end of this tutorial, you will understand every field in the manifest.json file, how to create one, and how it affects the installed PWA experience.

Why It Matters

The manifest is one of the three core PWA requirements. Without it, the browser does not know your app name, icon, or how to launch it. A well-configured manifest creates a seamless installation experience that feels native.

Real-World Use

Spotify's PWA manifest configures a standalone display with a dark theme color, high-resolution icons for different devices, and a short name that fits under the app icon on crowded home screens.

What a Manifest Does

When a user installs your PWA, the browser reads the manifest to determine:

  • What name and icon to show on the home screen
  • Whether to open the app in a browser tab or a standalone window
  • What color to use for the splash screen and address bar
  • Which URL to load when the app launches
  • How to orient the screen (portrait, landscape, or auto)
Manifest and the Installation Process
    Browser → Reads manifest.json → Shows install prompt
         ↓                              ↓
    User taps Install → App added to home screen
         ↓
    Tapping icon opens app → Browser uses manifest settings
    (standalone mode, theme color, start URL, orientation)

Think of the manifest like the label on a product box. Before you open the box, the label tells you the product name, brand, size, and what it looks like. The manifest tells the device what your app is before the user opens it.

Manifest Fields Explained

{
    "name": "My PWA Application",
    "short_name": "My PWA",
    "description": "A complete progressive web application",
    "start_url": "/dashboard?source=pwa",
    "display": "standalone",
    "orientation": "portrait-primary",
    "theme_color": "#3367D6",
    "background_color": "#ffffff",
    "icons": [
        {
            "src": "/icons/icon-192.png",
            "sizes": "192x192",
            "type": "image/png",
            "purpose": "any maskable"
        },
        {
            "src": "/icons/icon-512.png",
            "sizes": "512x512",
            "type": "image/png",
            "purpose": "any maskable"
        }
    ],
    "categories": ["education", "productivity"],
    "lang": "en-US",
    "dir": "ltr",
    "scope": "/",
    "related_applications": [
        {
            "platform": "play",
            "url": "https://play.google.com/store/apps/details?id=com.example"
        }
    ],
    "prefer_related_applications": false
}

Required Fields

  • name or short_name: At least one is required. name appears in the install prompt. short_name appears under the home screen icon.
  • icons: At least one 192x192 and one 512x512 icon. Provide multiple sizes for different devices.

Display Modes

The display field determines how your app looks when launched:

Mode Description
fullscreen Fills entire screen, no browser UI. Use for games and media.
standalone Opens in a separate window with no browser chrome. App-like experience.
minimal-ui Standalone with minimal navigation controls (back, forward).
browser Opens in the regular browser tab. Default fallback. 
<!-- Linking the manifest in your HTML -->
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="theme-color" content="#3367D6">
    <meta name="apple-mobile-web-app-capable" content="yes">
    <meta name="apple-mobile-web-app-status-bar-style" content="default">
    <link rel="manifest" href="/manifest.json">
    <link rel="apple-touch-icon" href="/icons/icon-192.png">
    <title>My PWA</title>
</head>
<body>
    <h1>Installable PWA</h1>
</body>
</html>

Icon Requirements

Icons must be square PNG images. Provide multiple sizes:

  • 48x48: Used for the browser install prompt
  • 72x72: Used on older Android devices
  • 96x96: Used on some notification areas
  • 128x128: Used in the install prompt
  • 144x144: Used on some tablets
  • 152x152: Used on iOS (apple-touch-icon)
  • 192x192: Required minimum for the manifest
  • 384x384: Used on Chrome OS
  • 512x512: Required for the splash screen and maskable icons

The purpose field tells the browser how to use the icon:

  • any: Use as-is, possibly with padding
  • maskable: Icon has safe zones and can be cropped into different shapes
  • monochrome: Browser can recolor the icon to match the theme
// Verify manifest loading in JavaScript
if ('manifest' in document) {
    const manifestLink = document.querySelector('link[rel="manifest"]');
    if (manifestLink) {
        console.log('Manifest found:', manifestLink.href);
        fetch(manifestLink.href)
            .then(response => response.json())
            .then(manifest => {
                console.log('App name:', manifest.name);
                console.log('Display mode:', manifest.display);
                console.log('Icons:', manifest.icons.length);
            });
    } else {
        console.log('No manifest link found');
    }
}

Output:

Manifest found: https://example.com/manifest.json
App name: My PWA Application
Display mode: standalone
Icons: 2

Scope and Start URL

The scope field defines which URLs are part of your PWA. Navigation outside the scope opens in a regular browser tab. The start_url defines the page loaded when the user opens the installed app.

{
    "scope": "/app/",
    "start_url": "/app/dashboard"
}

If scope is not set, it defaults to the directory where the manifest is located. Setting scope to / includes your entire site in the PWA experience.

Splash Screen

When a user opens an installed PWA, the browser shows a splash screen while the app loads. The splash screen uses:

  • background_color for the background
  • name for the title text
  • The 512x512 icon for the icon

A correctly configured splash screen makes the app feel instant. Without it, users see a white flash while waiting for content.

Common Mistakes

  1. Missing the 512x512 icon. Chrome requires a 512x512 icon for the splash screen. Without it, the install prompt may not fire.
  2. Incorrect icon paths. Icon paths are relative to the manifest file location, not the HTML page. Verify 404 errors in DevTools.
  3. No apple-touch-icon. iOS does not read the manifest icons. Add an apple-touch-icon link tag for iOS home screen icons.
  4. Scope too narrow. If a user navigates outside the scope, the browser opens a regular tab. Set scope to / unless you have a reason not to.
  5. Forgetting orientation. Without explicit orientation, your app may rotate unexpectedly. Set orientation to match your layout.

Practice Questions

  1. Which manifest fields are required for a PWA to be installable?
  2. What is the difference between fullscreen and standalone display modes?
  3. Why do you need both 192x192 and 512x512 icons?
  4. What happens when a user navigates outside the manifest scope?
  5. How do you configure iOS home screen icons separately from Android?

Challenge: Create a manifest.json for a fictional weather app. Include all recommended fields, icons at multiple sizes, and a splash screen configuration. Validate your JSON with Chrome DevTools.

FAQ

Can I update the manifest without redeploying?

Yes, the manifest is fetched on each page load. Deploy the updated manifest file and it applies to new visitors. Installed apps may need a service worker update to pick up changes.

What happens if display mode is not supported?

The browser falls back to the next available mode in order: fullscreen → standalone → minimal-ui → browser. Your app still works, but with less app-like appearance.

Do I need separate manifests for different languages?

Use the lang field for the default language. For multilingual PWAs, serve different manifest files based on the user's locale using server-side or JavaScript logic.

Can I use SVG icons in the manifest?

No. The manifest specification requires PNG icons. You can use an SVG for the favicon in HTML, but manifest icons must be PNG.

How do I test manifest changes?

Chrome DevTools → Application → Manifest panel shows a preview of how your manifest renders. The panel also reports validation errors.

Mini Project

Create a complete manifest.json for a note-taking PWA. Include: name, short_name, description, two icons (192x192 and 512x512 with maskable purpose), standalone display, portrait orientation, a theme color of your choice, and a scope of /. Link it in an HTML page and verify using Chrome DevTools.

What's Next

Your manifest is ready. Now you need a service worker to enable offline support. The service worker lifecycle lesson explains how service workers are installed, activated, and updated.

← Previous PWA vs Native Apps — Key Differences and When to Use Each Next → Service Worker Lifecycle — Install, Activate, and Fetch Explained

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Pwa