Frontend System Design · Lesson 62 of 86 · 4 min
PWA Manifest and Installability
This topic signals you understand how to bridge the gap between a web app and a native-like experience, a key product and engineering goal.
After this, you'll know exactly what makes a web app "installable" and how to control that experience. This isn't just about adding an icon to a home screen; it's about demonstrating you can deliver a reliable, integrated application that meets modern user expectations.
The Manifest: Your App's ID Card
The web app manifest is a JSON file, typically manifest.json, that you link in your HTML's <head>. It tells the browser and operating system how to treat your site as a standalone application. Without it, your app is just another tab.
Key properties you must know:
nameandshort_name: The full name for app stores or install prompts, and the short name for the home screen icon label.start_url: The entry point when a user launches the app from their home screen. The trap: This URL must be reachable offline. A common failure is pointing this to a route that isn't precached by your service worker. Use a relative path like/or/app.display: Defines the browser UI.standaloneis the one you want for an app-like feel; it hides the browser's address bar and navigation controls.fullscreenis for immersive experiences like games.icons: An array of image objects. You must provide at least a192x192and a512x512pixel icon. To show you're on top of things, also include amaskableicon, which ensures your icon looks good on all Android devices.background_colorandtheme_color:background_colorsets the splash screen color for a smoother transition on launch.theme_colortints the OS UI, like the status bar.
For extra credit, mention shortcuts to define a context menu for your app icon (like "New Document") or related_applications to link to your native App Store/Play Store app.
The Installability Checklist
A browser won't offer to install just any site. It runs a strict, automated check. Your PWA is only installable if it meets every criterion.
- Served over HTTPS. No exceptions.
- A valid manifest file is linked. No syntax errors, correct paths.
- A service worker is registered. It can be empty, but it must be there to signal offline capability.
- The
start_urlresponds with a 200, even offline. This proves the service worker is doing its basic job. - The manifest includes the required
192x192and512x512icons.
Browsers also use engagement heuristics (e.g., the user has visited twice with at least five minutes between visits). The install prompt won't appear on the first-ever page load.
This flow is deterministic. If the prompt isn't showing up, you've failed one of these checks.
In an interview, don't just list these criteria. Explain the why. HTTPS provides a secure context for an installed app. The service worker guarantees a baseline of reliability. The manifest provides the OS integration metadata. This shows you understand the principles, not just the recipe.
Taking Control of the Install Prompt
When the installability criteria are met, the browser fires the beforeinstallprompt event. Your job is to catch it, prevent the browser's default action, and show your own UI at the right moment.
The trap: Forgetting to call event.preventDefault(). If you don't, the browser may show its own small, easy-to-miss install banner. By preventing the default, you take full control of when and how the user is prompted.
Here is the complete implementation.
First, your manifest.json:
{
"name": "Frontend System Design App",
"short_name": "FSD App",
"start_url": ".",
"display": "standalone",
"background_color": "#fff",
"theme_color": "#3367D6",
"icons": [
{
"src": "images/icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "images/icons/icon-512x512.png",
"sizes": "512x512",
"type": "image/png"
}
]
}
Link it in your index.html and add a button:
<head>
<link rel="manifest" href="/manifest.json">
</head>
<body>
<button id="installButton" style="display: none;">Install App</button>
<script src="/app.js"></script>
</body>
Finally, the JavaScript logic in app.js:
let deferredPrompt;
const installButton = document.getElementById('installButton');
window.addEventListener('beforeinstallprompt', (e) => {
// Prevent the browser's default install prompt
e.preventDefault();
// Stash the event so it can be triggered later
deferredPrompt = e;
// Show your custom install button
installButton.style.display = 'block';
});
installButton.addEventListener('click', async () => {
if (!deferredPrompt) {
return;
}
// Show the browser's install prompt
deferredPrompt.prompt();
// Wait for the user to respond to the prompt
const { outcome } = await deferredPrompt.userChoice;
console.log(`User response to the install prompt: ${outcome}`);
// The prompt can only be used once. Clear it.
deferredPrompt = null;
installButton.style.display = 'none';
});
// Optional: Listen for when the app is successfully installed
window.addEventListener('appinstalled', () => {
deferredPrompt = null;
console.log('PWA was installed');
});
The userChoice promise resolves to an object with an outcome property: 'accepted' or 'dismissed'. You use this for analytics to understand how effective your custom UI is.
How to Debug When It Doesn't Work
When the install prompt doesn't appear, don't guess. Use your browser's tools.
In Chrome DevTools, go to the Application tab.
- Manifest: This pane shows how the browser parsed your
manifest.json. It will flag syntax errors, missing icons, and other problems. It also has an "Add to home screen" button to manually trigger the prompt for testing, bypassing the engagement heuristic. - Service Workers: Verify that your service worker is registered and running for the correct scope.
The fastest way to diagnose issues is to run a Lighthouse audit. Its PWA category checks all installability criteria and gives you a clear pass/fail report with instructions on how to fix any failures.
Try it
Create a minimal index.html, an empty service-worker.js, and a basic manifest.json. Serve them locally over HTTPS (tools like mkcert and http-server work well). Use DevTools to verify the installability criteria are met and that your custom install button successfully triggers the prompt.
Next: Service Workers: Lifecycle and Caching Strategies.
Lock it in — apply this lesson under interview conditions.