Skip to main content

Web App Manifest Link Tag for PWA Sites

Issue No: 132

Category: Link Rel Tags Issue type: Warning Priority: STANDARD

Description​

Pages that support Progressive Web App (PWA) features must declare a <link rel="manifest"> tag in the <head> pointing to a valid manifest.json file so browsers can enable PWA installation, home screen shortcuts, and app metadata.

How do we capture it​

Inside HTML <head>:

<link rel="manifest" href="/manifest.json">

The manifest file itself is a JSON document served at the href URL:

{
  "name": "My App",
  "short_name": "App",
  "start_url": "/",
  "display": "standalone",
  "icons": [...]
}
  1. Issues an HTTP GET to the target URL.
  2. Reads raw response bytes without JavaScript execution.
  3. Scans the <head> block for all <link> tags.
  4. Searches for a tag where rel equals manifest.
  5. Extracts the href attribute value.
  6. Issues a secondary HTTP GET to the manifest href URL.
  7. Records the HTTP status code and Content-Type response header from the manifest URL.

The crawler validates:

  • Whether a <link rel="manifest"> tag exists in the head.
  • Whether the href is a non-empty valid URL.
  • Whether the manifest URL returns HTTP 200.
  • Whether the manifest Content-Type is application/manifest+json or application/json.

What to store​

FieldTypeComment
has_manifest_linkBOOLEANWhether a web app manifest link tag is declared in the page head
manifest_hrefTEXTThe href value of the manifest link tag
manifest_href_statusINTHTTP status code returned when fetching the manifest URL
manifest_content_typeTEXTContent-Type response header returned by the manifest URL
manifest_is_valid_content_typeBOOLEANWhether the manifest Content-Type is application/manifest+json or application/json

Condition for trigger​

The following trigger rules evaluate manifest link presence and manifest file validity.

  • Trigger Rule 1: Missing Manifest Link Tag

    • Target Field: has_manifest_link
    • Evaluation Logic: = FALSE
    • Severity: SUGGESTION
    • Diagnostic Message: "No web app manifest link tag was detected. PWA installation and app metadata features will not be available for this page."

  • Trigger Rule 2: Manifest URL Not Reachable

    • Target Field: manifest_href_status
    • Evaluation Logic: NOT IN (200, 201, 204)
    • Severity: WARNING
    • Diagnostic Message: "The declared manifest URL does not return a valid HTTP response. Browsers cannot load the web app manifest and PWA features will be disabled."

  • Trigger Rule 3: Manifest Served With Wrong Content-Type

    • Target Field: manifest_is_valid_content_type
    • Evaluation Logic: = FALSE
    • Severity: STANDARD
    • Diagnostic Message: "The manifest file is not served with the correct Content-Type. Browsers may reject the manifest, preventing PWA installation."

Sources​

Long description​

The Web App Manifest is a JSON file that provides browsers with metadata about a Progressive Web App — including its name, icons, theme colors, start URL, and display mode. Linking to it via <link rel="manifest"> in the HTML head is the required mechanism for browsers to discover and read this metadata.

Standard manifest link tag:

<link rel="manifest" href="/manifest.json">

Minimal valid manifest.json:

{
  "name": "My Application",
  "short_name": "MyApp",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#000000",
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

Without a manifest link tag:

  • Browsers cannot offer the "Add to Home Screen" prompt.
  • PWA installability criteria are not met (Chrome, Edge, Safari).
  • App metadata like name, icons, and theme color are unavailable to the browser.
  • Lighthouse and PWA audit tools report a missing manifest as a failure.

With a broken manifest URL:

  • The browser fetches the link href and receives a 404 or server error.
  • The PWA manifest is silently ignored; no installation prompt appears.
  • The site may appear to support PWA from the HTML but behaves as a non-PWA.

Common failure scenarios:

  • Manifest link tag missing: The developer built a manifest file but never added the <link> tag to the HTML head.
  • Manifest URL returns 404: The tag is present but the file was moved or deleted, causing the HTTP fetch to return a non-2xx status code.
  • Wrong Content-Type header: The manifest file is served with text/plain or another incorrect MIME type instead of application/manifest+json. Some servers require manual MIME type configuration for .webmanifest or .json files.
  • Cross-origin manifest without proper headers: If the manifest is hosted on a different origin (e.g., CDN), it must include Access-Control-Allow-Origin: * or the browser will reject it.

How to Fix​

Add the manifest link tag inside the page <head>:

<link rel="manifest" href="/manifest.json">

Ensure the manifest file:

  • Is accessible at the declared href and returns HTTP 200.
  • Is served with Content-Type: application/manifest+json or application/json.
  • Contains at minimum name, start_url, display, and at least one icon entry.
  • If served from a CDN or separate origin, includes Access-Control-Allow-Origin: *.