Progressive Web Apps

Course 3 · Ch 7

manifest.json and the specific requirements that make a web page genuinely installable, with an icon and an app-like feel

Chapter 6's service worker is one half of what makes a Progressive Web App (PWA) — the other half is the web app manifest, a JSON file describing how the app should behave and present itself once installed. Together, they're what turns "just a website" into something a user can add to their home screen and open like a native app.

The Web App Manifest

// manifest.json
{
  "name": "My Learning Site",
  "short_name": "Learning",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#0d1117",
  "theme_color": "#e34c26",
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

// Linked from the page's <head>, like a stylesheet
<link rel="manifest" href="/manifest.json">

Property	Effect
name / short_name	Full app name vs the shorter version shown under the home screen icon
start_url	The URL opened when launched from the installed icon
display	standalone hides browser UI (address bar, tabs) — the app-like presentation that's the whole point
theme_color	Colours the OS status bar/title bar to match your brand on supporting platforms
icons	Multiple sizes — different OS/launcher contexts request different resolutions

The display Property — Choosing How "App-Like" It Feels

fullscreen — hides absolutely everything, including the OS status bar; mainly suited to games.
standalone — hides browser UI but keeps the OS status bar; the most common choice, looks genuinely like a native app.
minimal-ui — keeps a minimal set of browser navigation controls visible.
browser — opens as a completely normal browser tab, the default if no manifest exists at all.

What Actually Makes a Page Genuinely Installable

Browsers don't show the "Install" prompt for just any page with a manifest file — there's a specific, real checklist that must be satisfied first.

✅

Served over HTTPS

Same requirement as service workers (Chapter 6) — no exceptions besides localhost during development.

✅

A valid manifest.json, linked from the page

Including at minimum a name, icons of the required sizes, and a start_url.

✅

A registered service worker with at least a fetch event handler

Chapter 6's minimal example already satisfies this — the browser checks that the page can genuinely respond to network requests, even if just passing them through.

✅

Icons of the correct minimum sizes (typically 192×192 and 512×512)

Different platforms request different sizes — providing both common sizes covers the vast majority of cases.

Meeting the checklist doesn't guarantee an automatic install prompt appears

Browsers use their own internal heuristics (engagement signals, how the site has been used) on top of the technical checklist before showing a spontaneous "Add to Home Screen" prompt — meeting every requirement is necessary but not always sufficient for the prompt to appear automatically. Most real sites also offer their own explicit "Install App" button, triggered via the beforeinstallprompt event, rather than relying purely on the browser's own judgement.

Triggering Your Own Install Prompt

let deferredPrompt;

window.addEventListener('beforeinstallprompt', (event) => {
  event.preventDefault(); // stop the browser's automatic prompt
  deferredPrompt = event; // save it to trigger manually later
  document.getElementById('installButton').hidden = false;
});

document.getElementById('installButton').addEventListener('click', () => {
  deferredPrompt.prompt(); // shows the real browser install UI, on your own button click
});

PWA support and behaviour genuinely varies by platform

iOS Safari historically supported PWAs with notably more limitations than Android Chrome (different install flow, fewer manifest properties honoured, no automatic install prompt at all on iOS) — testing on the actual target platforms matters far more for PWAs than for most other features covered in this course.

Chapter 7 Quick Reference

manifest.json — name, icons, start_url, display mode; linked via <link rel="manifest">
display: standalone — the most common choice; hides browser UI, keeps OS status bar
Installability checklist: HTTPS, valid manifest, registered service worker with fetch handler, correctly sized icons
Meeting the checklist ≠ guaranteed automatic prompt — browsers add their own engagement heuristics on top
beforeinstallprompt + prompt() — trigger your own explicit "Install" button instead of relying on the browser alone
PWA support varies significantly by platform — test on actual target devices, especially iOS vs Android
Next chapter: accessibility deep dive — full ARIA patterns, keyboard navigation, screen reader testing