# Web app manifest: the minimal one that works

> The JSON file that makes a site installable — a minimal working manifest, how to link it, which members matter, and where each one is documented.

import { CardGrid, LinkCard } from '@astrojs/starlight/components';

The **web app manifest** is a JSON file that tells the browser how your site should
behave when it is installed as an app. It declares the app's identity (name, icons,
`id`), its installation boundary (`scope`), how it renders once launched (`display`),
and OS integration points such as shortcuts and `share_target`.

## A minimal manifest

```json
{
  "name": "Weather Reports",
  "short_name": "Weather",
  "start_url": "/",
  "display": "standalone",
  "icons": [
    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}
```

Link it from every page you want installable:

```html
<link rel="manifest" href="/manifest.webmanifest" />
```

The specification defines the manifest as an application manifest linked with
`rel="manifest"`; every member below is optional in the format itself. What a given
browser *requires* before it will offer installation is a separate, browser-specific
question — see [Install prompt](/reference/installation/install-prompt/) rather than
assuming the spec settles it.

## Which members to reach for first

- **Identity** — [`name` and `short_name`](/reference/manifest/name-short-name/) label the
  install prompt and the home-screen icon; [`id`](/reference/manifest/id/) pins the app's
  identity so a changed URL does not create a second install.
- **Entry and boundary** — [`start_url`](/reference/manifest/start-url/) is what launches;
  [`scope`](/reference/manifest/scope/) fences which URLs stay inside the app window.
- **Appearance** — [`display`](/reference/manifest/display/) (with
  [`display_override`](/reference/manifest/display-override/)) chooses the window shape;
  [`icons`](/reference/manifest/icons/) and
  [`theme_color`/`background_color`](/reference/manifest/theme-background-color/) supply the
  home screen and splash.

## Where it commonly goes wrong

- A `start_url` outside `scope` — the app launches, then immediately leaves its own window.
- Serving the manifest with the wrong content type, or from a path the page cannot reach.
- Changing `start_url` without setting `id`, which some browsers treat as a different app.
- Assuming a member is honoured everywhere; support varies per member and per platform.

Each linked page below carries its own browser-support table and cited sources.

## Every member in this section

<CardGrid>
	<LinkCard title="Manifest scope" href="/reference/manifest/scope/" description="The fenced boundary of your installed app — in-scope vs out-of-scope, share_target, shortcuts, and start_url." />
	<LinkCard title="start_url" href="/reference/manifest/start-url/" description="The entry-point URL your PWA loads on launch — scope constraints, UTM tracking, and deep-link handling." />
	<LinkCard title="id" href="/reference/manifest/id/" description="The stable identity of an installed PWA, independent of start_url." />
	<LinkCard title="name and short_name" href="/reference/manifest/name-short-name/" description="The full and abbreviated label for install prompts, home-screen icons, app switchers, and OS launchers." />
	<LinkCard title="Display modes" href="/reference/manifest/display/" description="standalone, fullscreen, minimal-ui, browser — the fallback chain and display_override." />
	<LinkCard title="display_override" href="/reference/manifest/display-override/" description="An explicit ordered fallback list that takes precedence over display." />
	<LinkCard title="Icons and maskable icons" href="/reference/manifest/icons/" description="The icon array for home screens, splash screens, and taskbars — including maskable icons for Android shaped icons." />
	<LinkCard title="theme_color and background_color" href="/reference/manifest/theme-background-color/" description="Tint the browser chrome and splash screen to match your brand — dark mode, meta tag interaction, and platform notes." />
	<LinkCard title="Screenshots" href="/reference/manifest/screenshots/" description="Promotional images for richer install dialogs — scrollable carousel and form_factor guidance." />
	<LinkCard title="Shortcuts" href="/reference/manifest/shortcuts/" description="Quick-action jump-list entries in the OS long-press and right-click context menu." />
	<LinkCard title="share_target" href="/reference/manifest/share-target/" description="Register your PWA in the OS native share sheet to receive shared URLs, text, and files from other apps." />
	<LinkCard title="file_handlers" href="/reference/manifest/file-handlers/" description="Register the PWA as a handler for file types the OS can open with it." />
	<LinkCard title="handle_links" href="/reference/manifest/handle-links/" description="Whether in-scope links open in the installed app or the browser." />
	<LinkCard title="launch_handler" href="/reference/manifest/launch-handler/" description="Whether a launch reuses an existing window or opens a new one." />
	<LinkCard title="Localization" href="/reference/manifest/localization/" description="lang, dir, and translations for a manifest that adapts to the user's locale." />
	<LinkCard title="related_applications" href="/reference/manifest/related-applications/" description="Point at native counterparts, and prefer_related_applications to favour them." />
	<LinkCard title="edge_side_panel" href="/reference/manifest/edge-side-panel/" description="Opt a PWA into Edge's side panel surface." />
	<LinkCard title="widgets" href="/reference/manifest/widgets/" description="The experimental widgets member for OS widget surfaces." />
	<LinkCard title="scope_extensions" href="/reference/manifest/scope-extensions/" description="Extend a PWA's scope across origins with the experimental scope_extensions member and its web-app-origin-association handshake." />
	<LinkCard title="Tabbed application mode" href="/reference/manifest/tabbed-display/" description="The experimental tabbed display_override value and the tab_strip member's home_tab and new_tab_button." />
	<LinkCard title="categories" href="/reference/manifest/categories/" description="Store-style category hints; metadata for catalogues, never rendered by the browser." />
	<LinkCard title="description" href="/reference/manifest/description/" description="Optional app-store text shown by richer install UI and store listings." />
	<LinkCard title="orientation" href="/reference/manifest/orientation/" description="Request a default screen orientation for the installed app window." />
	<LinkCard title="protocol_handlers" href="/reference/manifest/protocol-handlers/" description="Register the installed app as a handler for custom URL schemes." />
	<LinkCard title="Manifest updates" href="/reference/manifest/manifest-updates/" description="How installed PWAs pick up changes to the manifest, and which members never update in place." />
</CardGrid>

## Where to go next

- [Install prompt](/reference/installation/install-prompt/) — what browsers require before offering installation.
- [Service Worker](/reference/service-worker/) — the other half of an installable, offline-capable app.

← Back to the [Reference](/reference/) overview.