Metadata

In the context of Progressive Web Apps, metadata refers to the structured configuration that defines how your web app behaves when installed on a user’s device.

It is primarily defined through the manifest.json file and relevant <meta> tags in your HTML <head>, enabling:

App identity: name, icons, theme color
Display behavior: full-screen, standalone, or browser
Install experience: how and when install prompts appear
Device integration: splash screen, orientation, shortcuts

Valid manifest is required for browsers to consider your PWA installable. Without it, the install prompt won’t appear, and your app won’t behave like a native experience.

Keys of Metadata

⚠️

While the Web App Manifest specification includes a broader set of properties, this documentation highlights only the most essential fields necessary for a reliable installation experience and consistent app behavior across platforms.

Property	Type	Purpose
`app_name`	`string`	Full app name shown in install prompts and OS-level settings
`short_name`	`string`	Shortened name shown on homescreen or launcher
`description`	`string`	Describes the app’s purpose; may appear in installation dialogs
`app_id`	`string`	Unique identifier used for app packaging and internal registration
`start_url`	`string`	URL the app loads when launched
`scope`	`string`	Navigation scope of the PWA; outside this scope opens in browser
`display_mode`	`'standalone' \| 'fullscreen' \| 'minimal-ui' \| 'browser' \| 'window-controls-overlay'`	UI display behavior
`display_override`	`Array<'standalone' \| 'fullscreen' \| 'minimal-ui' \| 'browser' \| 'window-controls-overlay'>`	Preferred display modes in fallback order
`orientation`	`'portrait' \| 'landscape' \| 'portrait-primary' \| 'portrait-secondary' \| 'landscape-primary' \| 'landscape-secondary'`	Locks screen orientation
`theme_color`	`string`	Affects browser UI colors (taskbar, toolbar, etc.)
`background_color`	`string`	Splash screen background while app is loading
`prefer_native_apps`	`boolean`	Suggests browser prioritize native app if installed
`icons`	`Array<{ src: string; type: string; sizes: string }>`	App icon assets (multiple sizes and types) for homescreen/OS
`screenshots`	`Array<{ src: string; type: string; sizes: string; label: string }>`	Screenshots shown in install prompt to improve install quality signal

Example Manifest Snippet


{
  "app_name": "Satori PWA",
  "short_name": "Satori",
  "description": "Satori is your gateway to the web, offline.",
  "app_id": "com.satori.webapp",
  "start_url": "/",
  "scope": "/",
  "display_mode": "standalone",
  "display_override": ["standalone", "minimal-ui"],
  "orientation": "portrait",
  "theme_color": "#ffffff",
  "background_color": "#0f0e0e",
  "prefer_native_apps": true,
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "screenshots": [
    {
      "src": "/screenshots/screen1.png",
      "sizes": "750x1334",
      "type": "image/png"
    },
    {
      "src": "/screenshots/screen2.png",
      "sizes": "1200x800",
      "type": "image/png"
    }
  ]
}