1. Check the basics
Your site must be served over HTTPS. localhost also works for testing. Your pages should already work on a phone.
A step-by-step guide, the files you need with copy-ready code, what to change in your main site, AI prompts to paste into your tool, and a test checklist. No framework needed.
A Progressive Web App is a normal website that can be installed like an app and can open offline. You add a manifest, a service worker and icons. Your pages stay the same.
Your site must be served over HTTPS. localhost also works for testing. Your pages should already work on a phone.
Create a square logo of at least 512 by 512 pixels. Export PNG icons at 192 by 192 and 512 by 512, and a maskable 512 by 512 version with extra padding around the logo. Put them in an icons folder.
Add this file to the root of your site. It names your app and tells the browser which icons, colours and start page to use. Use the code in the files section below.
A simple page shown when the visitor has no connection and the page was not saved. Use your site's look and a short message.
The service worker saves your key files on first visit and serves them when the network is down. Put it in the root of your site so it covers every page.
On every page add the manifest link, the theme colour and the Apple icon link. The exact lines are in the files section.
Add the small registration script to your pages, or to a shared script file that every page loads.
Push your changes to GitHub so your host publishes them. See the deploy guides page if you need the steps.
Open your live site, press F12 and use the Application tab. Check Manifest for errors, Service Workers for status and Cache Storage for saved files. Then tick Offline in the Network tab and reload.
On desktop Chrome or Edge, use the install icon in the address bar. On Android Chrome, use the menu and Install app. On iPhone Safari, use Share and Add to Home Screen.
Whenever you change cached files, change the cache name in sw.js (for example from site-v1 to site-v2) so visitors get the new version.
Copy these into your project. Replace the names, colours and file lists with your own. Paths assume the site lives at the root of its domain.
Put in the site root. Names your app and sets its icons and colours.
{
"name": "My Site",
"short_name": "MySite",
"description": "A short description of my site",
"start_url": "/",
"scope": "/",
"display": "standalone",
"background_color": "#ffffff",
"theme_color": "#6c5ce7",
"icons": [
{ "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
{ "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" },
{ "src": "/icons/icon-maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
]
}Put in the site root. Saves files and shows the offline page when the network fails. List your real files in ASSETS.
const CACHE = 'site-v1'; // change v1 to v2, v3... on every release
const ASSETS = [
'/', '/index.html', '/offline.html',
'/style.css', '/app.js',
'/icons/icon-192.png'
];
self.addEventListener('install', (event) => {
event.waitUntil(caches.open(CACHE).then((c) => c.addAll(ASSETS)));
self.skipWaiting();
});
self.addEventListener('activate', (event) => {
event.waitUntil(
caches.keys()
.then((keys) => Promise.all(keys.filter((k) => k !== CACHE).map((k) => caches.delete(k))))
.then(() => self.clients.claim())
);
});
self.addEventListener('fetch', (event) => {
const req = event.request;
if (req.method !== 'GET') return;
if (req.mode === 'navigate') {
// Pages: network first, then cache, then the offline page
event.respondWith(
fetch(req).catch(() => caches.match(req).then((hit) => hit || caches.match('/offline.html')))
);
return;
}
// Files: cache first, then network
event.respondWith(caches.match(req).then((hit) => hit || fetch(req)));
});Put in the site root. Shown when a visitor is offline and the page is not saved.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>You are offline</title>
<style>
body { font-family: system-ui, sans-serif; display: grid; place-items: center; min-height: 100vh; margin: 0; text-align: center; }
</style>
</head>
<body>
<main>
<h1>You are offline</h1>
<p>Check your connection and try again. Pages you have visited may still work.</p>
<button onclick="location.reload()">Try again</button>
</main>
</body>
</html>Add inside the head tag.
<link rel="manifest" href="/manifest.webmanifest">
<meta name="theme-color" content="#6c5ce7">
<link rel="apple-touch-icon" href="/icons/icon-192.png">Add before the closing body tag, or in a script that every page loads.
<script>
if ('serviceWorker' in navigator) {
window.addEventListener('load', function () {
navigator.serviceWorker.register('/sw.js');
});
}
</script>Create these files in an icons folder: icon-192.png (192 by 192), icon-512.png (512 by 512) and icon-maskable-512.png (512 by 512, logo kept inside the centre 80 percent).
These are the edits that make an existing site installable and offline-ready. Miss one and the install button may not appear.
Service workers only run on HTTPS (and localhost). GitHub Pages, Cloudflare Pages, Netlify and Vercel provide HTTPS automatically.
A service worker can only control pages at or below its own folder. Put sw.js at the root so it covers the whole site.
Add <link rel="manifest" href="/manifest.webmanifest"> to the head of every page, not only the home page.
Add a theme-color meta tag and an apple-touch-icon link so the browser bar and iPhone home screen icon match your brand.
Add the registration script to a shared file or to every page. It is safe to run on each page.
If your site is at username.github.io/repo/, change / paths to relative ones: start_url and scope to ./, register sw.js without the leading slash, and list cached files without the leading slash.
If one file in the precache list returns an error, the whole install fails. Check each path in the browser.
Change the cache name each time you update cached files. Otherwise visitors can keep seeing old files.
Do not save login pages, personal data or live API results in the cache. Fetch those from the network.
If you use a Content Security Policy, make sure it allows your manifest and service worker files.
Do not set a long cache time on sw.js. If your host lets you set headers, use Cache-Control: no-cache for it.
Paste one into Claude, ChatGPT, Cursor or any AI tool along with your site files. Replace the [brackets].
Use first. Gives you every file and the exact edits.
Prompt: Turn my existing website into a Progressive Web App. Stack: [plain HTML, or your framework]. Hosting: [root domain, or a subfolder like github.io/repo]. Do these things: 1) Create manifest.webmanifest with name [full name], short_name [short name], start_url, scope, display standalone, background_color [hex], theme_color [hex], and icons of 192x192, 512x512 and a maskable 512x512 pointing to /icons/. 2) Create sw.js that precaches [list of pages and files], uses network-first for page navigations with a fallback to /offline.html, uses cache-first for static files, deletes old caches on activate and uses a versioned cache name. 3) Create offline.html in the same style as my site. 4) Show the exact lines to add to the head of every page (manifest link, theme-color, apple-touch-icon) and the script that registers the service worker. 5) List every file you created or changed with its path. If the site is in a subfolder, use relative paths so it still works. Do not change anything else. Finish with a testing checklist for Chrome DevTools.
Use when your site is at username.github.io/repo/.
Prompt: My site is hosted at [https://username.github.io/repo/] and I added a manifest.webmanifest and sw.js. Update all paths so they work from that subfolder: manifest start_url and scope, icon paths, the cache file list, the service worker registration and the offline fallback. Show each changed line.
Use when no install button appears.
Prompt: My site is not installable as a PWA. Here are the errors and warnings from Chrome DevTools, Application tab, Manifest: [paste]. Here are my manifest.webmanifest and sw.js: [paste]. Check HTTPS, name, icons, start_url, scope and service worker registration, and tell me exactly what to fix.
Use so visitors know when a new version is ready.
Prompt: Add an update banner to my PWA. When a new service worker is installed and waiting, show a small banner that says a new version is available with a Refresh button. The button should tell the waiting worker to activate and then reload the page. Show all code changes in sw.js and in my page script.
Use when you only have one logo.
Prompt: I have one square logo at [1024x1024 PNG]. Tell me which PWA icon sizes I need (192, 512 and a maskable 512), and give me commands or a free tool to generate them. Explain how much padding a maskable icon needs.
Check each of these before you tell anyone the site works offline.
In Chrome, press F12, open Application, then Manifest. Fix any red errors. You should see your name, icons and colours.
In Application, Service Workers, the status should be activated and running. Use Update on reload while testing.
In Application, Cache Storage, open your cache. Every file from your list should be there.
In the Network tab, tick Offline and reload. Your page or the offline page should appear, not a browser error.
Desktop Chrome and Edge show an install icon in the address bar. Android Chrome shows Install app in the menu. On iPhone use Safari, Share, Add to Home Screen.
In Application, Storage, choose Clear site data, unregister the service worker and reload. Old versions can hide new changes.
Free tools and guides for building and checking a PWA.
Checks your site and helps create a manifest and packages for app stores.
Free: Free
VisitFree course on Progressive Web Apps by Google.
Free: Free
VisitReference guides on manifests, service workers and installability.
Free: Free
VisitGoogle's library that simplifies caching strategies in service workers.
Free: Free
VisitAdds PWA support to Vite projects, including React, Vue and Svelte.
Free: Free
VisitPreview your icon in different mask shapes before you export it.
Free: Free
VisitCreate favicons and app icons for many platforms from one image.
Free: Free
VisitCheck which browsers support service workers.
Free: Free
Visit