{"canonical_url":"https://engineer.company/glossary/webmanifest/","content_markdown":"# Web app manifest\n\n## What it is\n\nA web app manifest is a JSON document that describes a website as an\napplication: what it is called, which address it opens at, which addresses\nbelong to it, how its window should look and which pictures stand for it. A page\npoints to the file with a `link` element whose `rel` is `manifest`, and a\nbrowser that offers installation reads it to decide what the installed copy will\nbe. The W3C specification that defines it calls it just the manifest, and so\ndoes most everyday talk about it.\n\nThe file is plain JSON. Its registered media type is `application/manifest+json`\nand its registered extension is `.webmanifest`, although the specification\naccepts any JSON media type and plenty of sites serve a `manifest.json`. Every\nmember is optional. A small one for an imaginary tide-table site looks like\nthis:\n\n```json\n{\n    \"name\": \"Harbour Tide Tables\",\n    \"short_name\": \"Tides\",\n    \"start_url\": \"/tides/\",\n    \"display\": \"standalone\",\n    \"background_color\": \"#ffffff\",\n    \"icons\": [\n        {\n            \"src\": \"/icons/tides-512.png\",\n            \"sizes\": \"512x512\",\n            \"type\": \"image/png\"\n        }\n    ]\n}\n```\n\nThree members decide what the app is, as distinct from how it looks.\n`start_url` suggests the page the installed app opens at; a browser may ignore\nit or let the user change it. `scope` is the set of addresses that count as\ninside the app; when it is missing, the specification takes the start URL with\nits file name, query and fragment cut off, so the example above owns\neverything under `/tides/`. `id` is the app's identity, and when it is missing\nit falls back to the start URL. Relative icon addresses and the start URL\nresolve against the manifest's own URL rather than the page that linked to it.\nA relative `id` instead resolves against the start URL's origin.\n\nThe rest is presentation. `display` asks for `fullscreen`, `standalone`,\n`minimal-ui` or `browser`, and a browser that cannot honour the request steps\ndown that list in order. Each icon may carry a `purpose`: `any` by default,\n`maskable` for a picture drawn to survive cropping, or `monochrome` for one\nwhose colour is thrown away so that only its alpha channel is used.\n`theme_color` tints the window around the app. A companion W3C note adds\n`description`, `categories` and `screenshots`, which install dialogs and stores\nmay show.\n\n## Why it matters\n\nThe manifest supplies installation metadata that the site controls. The\nspecification leaves the decision to install with the browser: it may offer a\nway to install, and each browser sets its own conditions, some of which\nrequire particular members. A team ships the input and the browser decides\nwhat to do with it, so the useful question is less whether to have a manifest\nthan what it promises.\n\nIdentity is the promise that outlives the file. When a browser fetches the\nmanifest again, the specification says it should use a matching `id` as a\nsignal that the new file replaces the manifest of an app already installed.\nBecause a missing `id` is the start URL, moving the start page quietly changes\nthe identity, so the browser should treat the new file as a different\napplication from the one on the reader's device. Pinning `id` on the first\nrelease costs one line and removes that risk.\n\nScope decides where the app window ends. Navigation inside the scope stays in\nthe installed window. A link that leaves it still opens, but the specification\nexpects the browser to show the reader that they are outside the app, so a scope\nnarrower than the site makes ordinary links between its sections look like\nexits.\n\nIcons are where most of the visible damage happens. Launchers crop icons to\ncircles, rounded squares and other shapes, and a logo that fills its whole\nsquare loses its edges. The specification defines the safe zone of a maskable\nicon as a circle in the middle with a radius of two fifths of the icon's\nshorter side, and anything outside it may be cut. A monochrome icon keeps only\nits alpha channel, so an icon drawn on an opaque background turns into a solid\nsquare.\n\nThe colour members are narrower than they look. `background_color` is meant only\nfor the moment before the stylesheet arrives, and the specification forbids the\nbrowser from using it once the stylesheet is available. It is the colour of the\nfirst frame, and nothing after it.\n\n## What it looks like in practice\n\nThis site builds its manifest from a template rather than keeping a file by\nhand. Its Hugo configuration registers `application/manifest+json` with the\nsuffix `webmanifest` and makes the manifest an output of each language's home\npage, so every language gets its own file, and the head of each page links the\nfile for its own language. The configuration records why: a single global copy\ncan name only one start URL, and a Danish visitor who installed the site got an\napp that opened the English home.\n\nThe template assembles the manifest as a map and hands it to Hugo's JSON\nencoder, so escaping and commas are the encoder's problem and a missing comma\ncannot ship. Every icon address starts at the root of the host. Its comment\nspells out the reason: a relative address in `/da/manifest.webmanifest` would\nresolve under `/da/`, and every icon in Danish would 404. The icons themselves\nare read off disk from three folders, one per purpose, ten sizes each from 36 to\n512 pixels, with the size taken from the file name, so a size added by the\ngenerator appears in the manifest with nothing to edit.\n\n`id` is pinned to the language's home address, and `scope` is the whole origin,\nso a link into another language stays inside the installed window. Screenshots\nare named `\u003clang\u003e-\u003cform_factor\u003e-\u003cWxH\u003e.webp`, and the template reads all three\nfacts off the file name: English and Danish each carry one wide shot at 1280 by\n800 and one narrow shot at 780 by 1688. A language without screenshots gets no\n`screenshots` member at all, rather than an empty list.\n\n[The credits page](/credits/) lists the W3C specification among the standards\nthe site follows, and PWABuilder among the outside checks anyone can run: a\nservice that reads the manifest and the rest of what makes the site installable,\nfrom Microsoft's machines.\n\n[The install page](/install/) is the reader's half of the same file. It walks\nthrough where each browser keeps the install command and notes that Apple's\nbrowsers never offer it unprompted. Firefox has a separate web-app window\nfeature enabled by default on Windows from version 143, or version 150 for\nMicrosoft Store installations. Mozilla's implementation documentation lists\nLinux support as disabled by default and macOS support as unavailable. The\npage also sets expectations for this site: the installed app is an icon and a\nwindow of its own. The site publishes no service worker or managed offline\ncopy, so it needs a connection for normal use.\n\n## Where it goes wrong\n\n**Every icon 404s on a translated path.** A relative `src` resolves against the\nmanifest's URL, so a manifest served from a language prefix asks for icons under\nthat prefix. Write icon addresses from the root of the host, or as full URLs.\n\n**The installed app opens in the wrong language.** One manifest can name one\nstart URL, so every reader installs the same home page. Serve one manifest per\nlanguage, each with its own `start_url` and `id`, and link the matching one from\neach page.\n\n**Installed copies ignore the new manifest.** With no `id`, the identity is\nthe start URL, so moving the start page gives the file a new identity, and the\nbrowser should treat it as a different app from the one readers already have.\nSet `id` before the first release and leave it alone afterwards.\n\n**The launcher crops the logo.** An icon with purpose `any` is placed or cut\nas the platform sees fit. Add a `maskable` icon with everything that matters\ninside the central circle whose radius is 40% of the icon's shorter side.\n\n**Edits to the manifest change nothing.** The HTML standard uses only the first\n`link` element whose `rel` contains `manifest`, so when a theme or plugin has\nput its own link earlier in the page, the file being edited is never the one\nread. Keep exactly one manifest link per page.\n\n## Further reading\n\n- [Web Application Manifest](https://www.w3.org/TR/appmanifest/) — every member,\n  how a browser processes the file, and the rules for `id`, `scope` and icon\n  purposes.\n- [Web App Manifest - Application Information](https://www.w3.org/TR/manifest-app-info/)\n  — `description`, `categories` and `screenshots`, with form factors and labels.\n- [IANA: application/manifest+json](https://www.iana.org/assignments/media-types/application/manifest+json)\n  — the registration of the media type and its `.webmanifest` extension.\n- [HTML Standard: link type manifest](https://html.spec.whatwg.org/multipage/links.html#link-type-manifest)\n  — how the manifest link is fetched and why only the first one counts.\n- [Use web apps in Firefox for Windows](https://support.mozilla.org/en-US/kb/web-apps-firefox-windows)\n  — the Windows feature and its version 143 and Microsoft Store version 150\n  availability.\n- [Firefox Source Docs: Web Apps in Firefox](https://firefox-source-docs.mozilla.org/browser/components/taskbartabs/docs/index.html)\n  — the current implementation: Windows enabled by default, Linux disabled by\n  default, and macOS unsupported.\n\n\u003chttps://engineer.company/glossary/webmanifest/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"What a web app manifest's members decide for an installed site, why its id has to stay fixed, and what launchers do to the icons it lists.","formats":{"gemtext":"https://engineer.company/glossary/webmanifest/index.gmi","gopher":"https://engineer.company/glossary/webmanifest/gophermap","html":"https://engineer.company/glossary/webmanifest/","json":"https://engineer.company/glossary/webmanifest/index.json","markdown":"https://engineer.company/glossary/webmanifest/index.md","pdf":"https://engineer.company/glossary/webmanifest/index.pdf"},"kind":"page","language":"en","title":"What is a web app manifest?","url":"https://engineer.company/glossary/webmanifest/","version":1}