How to make a website installable

#What installable means

An installed website gets its own icon on the home screen, in the dock or in the Start menu, opens in its own window without the address bar, shows up in the app switcher and can be uninstalled like any app. Nothing about the website changes for visitors who never install it. The browser decides whether to offer the install, and it decides from a few files you control.

On Android and desktop, Chromium browsers (Chrome, Edge, Samsung Internet, Opera, Brave) show an install icon in the address bar and may fire a beforeinstallprompt event that lets your page show its own button. Safari on iPhone and iPad never prompts: the visitor installs through Share and Add to Home Screen, which works for any page but looks far better when the site provides the right icon and metadata.

#The checklist browsers use

1. A web app manifest, linked from the page with <link rel="manifest">, that loads and parses as JSON.
2. A name: name or short_name. The short name is the label under the icon and should fit in 12 characters.
3. Icons of 192 and 512 pixels with purpose any. Most browsers also use a maskable icon when one is listed.
4. An app display mode: standalone, fullscreen or minimal-ui. With browser the site is not installable.
5. A start_url on the same origin and inside the scope.
6. HTTPS. Service workers and installs need a secure origin; localhost counts while you develop.
7. A service worker with a fetch handler, so the app opens when the network is gone.

Chrome also waits for a little engagement before it fires the prompt, so the button may appear only after the visitor has clicked or tapped on the page once.

#Doing it by hand

The manifest is a JSON file, usually manifest.webmanifest at the site root. URLs inside it are relative to the manifest itself, so ./ means the folder it sits in:

{
  "id": "./",
  "name": "Acme Bakery",
  "short_name": "Acme",
  "start_url": "./",
  "scope": "./",
  "display": "standalone",
  "theme_color": "#e8590c",
  "background_color": "#ffffff",
  "icons": [
    { "src": "icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
    { "src": "icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
    { "src": "icons/maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ]
}

Then link it, add the iOS and theme tags, and register a service worker from every page:

<link rel="manifest" href="/manifest.webmanifest">
<meta name="theme-color" content="#e8590c">
<link rel="apple-touch-icon" href="/apple-touch-icon.png">
<meta name="apple-mobile-web-app-title" content="Acme">
<script>
  if ('serviceWorker' in navigator) {
    addEventListener('load', () => navigator.serviceWorker.register('/sw.js'));
  }
</script>

The service worker needs at least a fetch handler, and to be useful offline it should cache your pages. The offline page guide walks through a worker that does that well, and the icon sizes guide lists every image you need.

#Doing it in one command

installkite automates every item on the checklist. In the folder of a static site, or in a Vite, Next.js or Astro project, run:

npx installkite init

It reads the name, description, language and theme color from your home page, finds your logo, asks a few questions and writes the manifest, ten icon sizes plus maskable icons, the apple-touch-icon and favicons, a service worker that precaches your pages, an offline page and a 4 kB runtime that registers the worker and shows an install button. The head tags go into every HTML page between two marker comments, so running it again updates them instead of adding duplicates. Add --dry-run first to read a diff of every change.

#Testing the install

Serve the site over HTTPS, or from localhost, and open it in Chrome or Edge. The Application panel of the developer tools shows the parsed manifest, the icons and any installability errors, and the install icon appears at the right of the address bar. On Android, open the browser menu and look for Install app. On iPhone, tap Share and check that the icon and name in the Add to Home Screen sheet are yours.

Before you deploy, run the audit:

npx installkite doctor                          # the files on disk
npx installkite doctor --url https://acme.example/   # the live site

Doctor checks every rule above, plus the icon files and their real pixel sizes, the service worker scope and whether the precache list matches your files, and prints a fix next to each failure.

#Why the install button does not appear

• The page is on HTTP. Only HTTPS and localhost are secure origins.
• The manifest returns 404, often because the link uses /manifest.webmanifest on a site served from a subfolder such as a GitHub Pages project. Use the right base path or relative URLs.
• An icon is missing or its file is not the size the manifest claims.
• The site is already installed. Browsers hide the prompt for installed apps.
• The visitor dismissed the prompt; Chrome waits a while before it offers again.
• The browser does not install sites, like Firefox on desktop. Your site still works there as a website.

#Questions

#Keep reading