Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 37 ยท Web App Manifest

Web App Manifest Basics

Learn the core fields of a web app manifest: name, short_name, description, start_url, scope and id, how to link it, and how browsers resolve its URLs.

The web app manifest is a JSON file that tells the browser who your app is. Without it your site is just a website; with it, the browser can show a proper name and icon, open the app in its own window, and offer installation. It is the easiest part of a PWA to write and the part where small mistakes (a wrong path, a missing field) quietly switch features off.

This lesson covers the identity and navigation fields. The next lessons add icons, display modes, colors and the optional features.

Linking the manifest

Add one link element to the <head> of every page:

HTML
<link rel="manifest" href="/manifest.webmanifest">

The conventional file extension is .webmanifest and its media type is application/manifest+json. A plain .json file works if the server sends a JSON content type, but .webmanifest is the standard. If your page and manifest are on different origins you need crossorigin="use-credentials" when the manifest requires cookies; most sites never do.

Relative URLs inside the manifest (icons, start_url) are resolved against the manifest's own URL, not the page's URL. That is one of the most common sources of broken icons: put the manifest at the root, or use absolute paths starting with /.

Names

JSON
{
  "name": "Trail Notes: Hiking Journal",
  "short_name": "Trail Notes",
  "description": "Write notes on the trail and keep them offline."
}
  • name is the full name. Browsers show it in the install dialog, the splash screen and app lists. Keep it clear and unique.
  • short_name is used where space is tight, such as under the home screen icon. About 12 characters or fewer avoids truncation on most devices.
  • description explains the app, shown in install dialogs on some platforms and in app stores that index PWAs.

If short_name is missing, the browser uses name, which may be cut off. Always provide both.

start_url

start_url is the page that opens when the user launches the installed app. It is resolved against the manifest URL. Several rules help you:

  • Use a URL that works offline (it must be cached by the service worker).
  • Add a query string to track installed launches in analytics: "start_url": "/?source=pwa". Make sure your server and cache treat it correctly; the service worker may need ignoreSearch when matching (see the Cache API lesson).
  • It must be inside the scope, otherwise the install check fails.
JSON
{ "start_url": "/?source=pwa" }

scope

scope defines which URLs belong to the app. While the user navigates within the scope, the app stays in its own window. A link to a URL outside the scope opens in a browser tab or an in-app browser overlay, depending on the platform.

JSON
{ "scope": "/app/" }

If you omit scope, it defaults to the directory containing start_url. A start_url of /app/home gives the default scope /app/. Setting "scope": "/" includes the whole origin. Note that the manifest scope is separate from the service worker scope; they can differ, but keeping them aligned avoids surprises.

Trailing slash matters: /app and /app/ are not the same prefix. A scope of /app/ does not contain /app itself.

id

The id gives your app a stable identity. Browsers use it to decide whether two installs are the same app. Without it, the identity is derived from start_url, so changing start_url later makes the browser think it is a new app. With id you can move start_url freely:

JSON
{
  "id": "/trail-notes",
  "start_url": "/?source=pwa"
}

id is resolved against the origin, so "/trail-notes" becomes https://notes.example/trail-notes. Set it from day one and never change it.

lang, dir and categories

JSON
{
  "lang": "en",
  "dir": "ltr",
  "categories": ["productivity", "lifestyle"]
}

lang and dir give the language and text direction of the manifest strings (use rtl for right-to-left languages). categories is a hint for stores and catalogs.

Resolving URLs: a runnable stand-in

URL resolution trips up many beginners, so here is a runnable example using the URL class, which is the same mechanism the browser uses. Change the manifest URL and see what happens to the icon.

JS How manifest URLs are resolved

Press Run (or Ctrl + Enter) to see the console output here.

No output.

In this example both URLs match because the manifest and page share a folder. Move the manifest to /manifest.webmanifest in your head and the first line changes. Rule of thumb: use root-relative paths and put the manifest at the root.

A manifest checker for identity fields

Let us put the rules into code. This stand-in checks start_url against scope and warns about the common mistakes from this lesson.

JS Check start_url against scope

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The manifest also reaches search and stores

Because the manifest holds the name, description and categories, other platforms can index your PWA. Some app stores (for example Microsoft Store through packaging tools) read it directly. A good description and category make your listing there easier. Chapter 8 covers distribution.

Common mistakes

  • Putting a comment or trailing comma in the JSON. Manifests are strict JSON; the Console shows a parse error.
  • Using a start_url that redirects. Redirects can break installability and confuse offline caching.
  • Forgetting that changing start_url or id after launch creates a new app identity.
  • Serving the manifest with an auth requirement the browser does not know about.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Relative URLs inside a manifest are resolved against which URL?

    The manifest's own URL is the base, so moving the file changes the meaning of relative paths.
  2. 2. What is the purpose of the id member?

    id lets you change start_url later without browsers treating the app as a different one.
  3. 3. What happens when a user navigates to a URL outside the manifest scope inside the installed app?

    Out-of-scope navigations leave the app window and open as normal browser pages or in an overlay.
  4. 4. Which short_name is the best choice for a home screen label?

    Short, clear names avoid truncation under the icon.

Summary

  • Link the manifest with <link rel="manifest">; its relative URLs resolve against the manifest's own URL.
  • Provide both name and short_name, plus a description.
  • start_url must be inside scope and should work offline.
  • Set a permanent id so the app identity survives later changes.
  • Manifest JSON must be strictly valid.

Next: Manifest Icons