How to make an AI-built web app installable (PWA)
Make an AI-built web app installable as a PWA: the exact manifest fields, icon sizes, what each browser does, and an install button with an iOS fallback.
To make an AI-built web app installable, link a web app manifest from every page, serve the site over HTTPS, give the manifest a name, a start URL, a display mode and 192 and 512 pixel icons, and you are done for Chromium browsers. A service worker is not required for installation, despite what many tutorials say. What changes between browsers is how people are offered the install, and that is where most of the work in this guide goes.
The requirements below come from MDN's guide to making PWAs installable and web.dev's manifest guide.
What it means to make an AI-built web app installable
An installed web app opens in its own window or full screen, gets an icon on the home screen or launcher, and can appear in the app switcher. It is still your website. There is no app store, no review process and no separate codebase. For many small products this covers what people mean by "I want an app". Can AI build a mobile app discusses when it does not.
The requirements
For Chromium-based browsers (Chrome, Edge, Samsung Internet), MDN lists these:
A manifest linked with
<link rel="manifest" href="/manifest.webmanifest">. On a multi-page site, every page needs it.The manifest includes
nameorshort_name,icons,start_url, anddisplayordisplay_override.The
iconsarray "must contain a 192px and a 512px icon".prefer_related_applicationsmust befalseor absent.The site is served over HTTPS, or from
localhostor127.0.0.1during development.
On the service worker, MDN is direct: it is "not a requirement for a PWA to be installable", although many PWAs use one for offline support. If you want that, adding offline support to an AI-built app is the next step. Do not add a service worker only to satisfy a checklist. A badly written one can serve stale pages for weeks.
A working manifest
{
"id": "/",
"name": "Acme Bookings",
"short_name": "Bookings",
"start_url": "/dashboard?source=pwa",
"scope": "/",
"display": "standalone",
"background_color": "#ffffff",
"theme_color": "#1a1a2e",
"icons": [
{ "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
{ "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" },
{ "src": "/icons/maskable-512.png", "sizes": "512x512",
"type": "image/png", "purpose": "maskable" }
]
}And in the page head:
<link rel="manifest" href="/manifest.webmanifest">
<meta name="theme-color" content="#1a1a2e">Choices worth making on purpose, following web.dev's advice:
`start_url` should drop people into the app, not a marketing page. Adding
?source=pwalets you tell installed visits from browser visits in analytics.`id` decouples the app's identity from the start URL and manifest location, so you can change either later without the browser treating it as a new app.
`display: standalone` hides the address bar. Other values are
fullscreen,minimal-uiandbrowser. Usedisplay_overrideif you want a custom fallback order.`background_color` should match your page's load colour so the splash screen does not flash.
`theme_color` sets the toolbar colour. Keep it in sync with the
metatag. You cannot define light and dark values in the manifest, but you can use amediaattribute on the meta tags.A maskable icon (
"purpose": "maskable") lets Android crop your icon into whatever shape the device uses. Keep the important artwork in the centre.
If you only supply the 192 and 512 icons, Chrome scales them for each device. For crisp results everywhere, add more sizes.
What each platform actually does
Install support is uneven. MDN's summary, condensed:
Chromium on desktop and Android: install from a prompt or the browser menu when a valid manifest exists. On Android, Chrome (on devices with Google Mobile Services) and Samsung Internet install a full WebAPK with a real launcher entry. Other Android browsers add a home-screen shortcut that opens in the browser.
Safari on macOS Sonoma (Safari 17) and later: "Add to Dock" works for any web app, with or without a manifest.
Firefox on desktop: does not support installing PWAs from a manifest.
iOS 16.4 and later: install from the Share menu in Safari, Chrome, Edge, Firefox and Orion. On iOS 16.3 and earlier, only Safari can install.
Install without a manifest: Chrome on desktop and Android, desktop Safari and desktop Edge let users install any website as an app. A manifest lets the browser promote the install and style it.
The consequence: do not tell every user to "tap Install". Detect what they have.
An install button that behaves
Chromium fires a beforeinstallprompt event that lets you show your own button. MDN notes it is not supported on iOS, so you need a second path:
let deferredPrompt = null;
const btn = document.querySelector('#install');
window.addEventListener('beforeinstallprompt', (e) => {
e.preventDefault();
deferredPrompt = e;
btn.hidden = false;
});
btn.addEventListener('click', async () => {
if (!deferredPrompt) return;
deferredPrompt.prompt();
await deferredPrompt.userChoice;
deferredPrompt = null;
btn.hidden = true;
});
const isStandalone =
window.matchMedia('(display-mode: standalone)').matches ||
navigator.standalone === true;
const isIOS = /iphone|ipad|ipod/i.test(navigator.userAgent);
if (isIOS && !isStandalone) {
document.querySelector('#ios-hint').hidden = false;
// "Tap Share, then Add to Home Screen."
}Two rules for the button. Never show it to someone who is already running the installed app, which is what the isStandalone check is for. And do not show it on first visit. Wait until the person has done something useful, such as completing a booking.
Measure installs without guessing
Browsers that support installation fire an appinstalled event, and the (display-mode: standalone) media query tells you whether a visit is from the installed app. Log both as simple analytics events. Combined with the ?source=pwa start URL, you can see how many installs happen and whether installed users come back more often. If nobody installs, the prompt or the moment you show it is the first thing to change, not the manifest.
Common mistakes to look for
Icon paths that return 404. The manifest looks fine and the install silently fails. Open each icon URL.
A manifest linked only from the home page. MDN says every page needs the link if the app has several pages.
`start_url` pointing at a redirect. A start URL that bounces through a login page can land installed users somewhere odd. Point it at a route that handles signed-out users cleanly.
Theme colour that clashes with the page. The toolbar and the page header should match, or the app looks unfinished.
Treating install as the goal. An installed app that is slow or confusing is worse than a good website. Fix the basics first.
A prompt to start from
Make this web app installable. Add a manifest.webmanifest with id, name, short_name, start_url, scope, display standalone, theme and background colours, and 192, 512 and maskable 512 icons. Link it and the theme-color meta tag on every page. Do not add a service worker. Add an install button that appears only when beforeinstallprompt fires and a one-line hint for iOS Safari users, hidden when the app is already in standalone mode.
Then check the output against the list above. Look for a service worker you did not ask for and for a missing maskable icon.
Changing things after people have installed
Installed apps are harder to change than web pages, so decide a few things early. Set the id in the manifest from the start and never change it, since it is what ties the installed app to its identity. Keep icon filenames stable or version them, and watch for icons cached on user devices. If you change the start_url or icons later, test with both a fresh install and an existing one.
Test it
Open Chrome DevTools, go to the Application panel, and read the Manifest pane. It reports missing fields and icon problems. web.dev recommends this check.
Install on desktop Chrome and confirm the window opens at your
start_url.On an Android phone, install and look for the launcher icon and splash screen colour.
On an iPhone, use Share then Add to Home Screen and check the icon is not a screenshot of your page.
Open the installed app with no network. If you did not add offline support, the browser error page is expected. Decide whether that is acceptable.
Push notifications are a separate feature with their own requirements, covered in adding push notifications to an AI-built app. Large icons and screenshots are worth compressing, and optimising images in an AI-built app covers that. For the overall approach, see how to build an app with AI.
FAQ
Does a PWA need a service worker to be installable?
No. MDN says a service worker is not required for installation. It is only needed if you want offline behaviour or other features that depend on one.
Can iPhone users install a PWA?
Yes. On iOS 16.4 and later, installation is available from the Share menu in Safari, Chrome, Edge, Firefox and Orion. There is no automatic install prompt on iOS, so show instructions.
What icon sizes does a PWA manifest need?
Chromium browsers require a 192 by 192 and a 512 by 512 pixel icon. Adding a maskable icon is strongly recommended for Android.
Why is there no install button in Firefox on desktop?
Firefox on desktop does not support installing PWAs using a manifest file, so there is nothing to prompt.
How did this land?
About the author

Developer Advocate
Steve builds something with Swarmz every week and writes up what worked, what broke, and what he'd do differently. Tutorials and hands-on guides are his lane.


