Home FAQ New Contact About
Developer topics

Turn a site into a PWA installable and works offline

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.

Guide: turn your site into a PWA

11 steps

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.

1. Check the basics

Your site must be served over HTTPS. localhost also works for testing. Your pages should already work on a phone.

2. Make your icons

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.

3. Create manifest.webmanifest

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.

4. Create offline.html

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.

5. Create sw.js

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.

6. Add the tags to your head

On every page add the manifest link, the theme colour and the Apple icon link. The exact lines are in the files section.

7. Register the service worker

Add the small registration script to your pages, or to a shared script file that every page loads.

8. Deploy the changes

Push your changes to GitHub so your host publishes them. See the deploy guides page if you need the steps.

9. Test in Chrome DevTools

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.

10. Install it

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.

11. Update later

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.

Files you need and the code

6

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.

manifest.webmanifest

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" }
  ]
}

sw.js

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)));
});

offline.html

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>

Tags for the head of every page

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">

Service worker registration

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>

Icons folder

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).

What to change in your main site

11

These are the edits that make an existing site installable and offline-ready. Miss one and the install button may not appear.

Serve it over HTTPS

Service workers only run on HTTPS (and localhost). GitHub Pages, Cloudflare Pages, Netlify and Vercel provide HTTPS automatically.

Put manifest and sw.js at the root

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.

Link the manifest on every page

Add <link rel="manifest" href="/manifest.webmanifest"> to the head of every page, not only the home page.

Add theme and icon tags

Add a theme-color meta tag and an apple-touch-icon link so the browser bar and iPhone home screen icon match your brand.

Register the service worker once

Add the registration script to a shared file or to every page. It is safe to run on each page.

Fix paths for subfolder hosting

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.

List only files that exist

If one file in the precache list returns an error, the whole install fails. Check each path in the browser.

Version your cache

Change the cache name each time you update cached files. Otherwise visitors can keep seeing old files.

Do not cache private or changing data

Do not save login pages, personal data or live API results in the cache. Fetch those from the network.

Check your security headers

If you use a Content Security Policy, make sure it allows your manifest and service worker files.

Do not cache sw.js for long

Do not set a long cache time on sw.js. If your host lets you set headers, use Cache-Control: no-cache for it.

Prompts to paste into your AI tool

5

Paste one into Claude, ChatGPT, Cursor or any AI tool along with your site files. Replace the [brackets].

Add PWA support to my site

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.

Fix paths for a subfolder

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.

Find out why it is not installable

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.

Add an update banner

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.

Generate my icons

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.

Test, install and troubleshoot

6

Check each of these before you tell anyone the site works offline.

Check the manifest

In Chrome, press F12, open Application, then Manifest. Fix any red errors. You should see your name, icons and colours.

Check the service worker

In Application, Service Workers, the status should be activated and running. Use Update on reload while testing.

Check the saved files

In Application, Cache Storage, open your cache. Every file from your list should be there.

Test offline

In the Network tab, tick Offline and reload. Your page or the offline page should appear, not a browser error.

Install on desktop and phones

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.

If something is stuck

In Application, Storage, choose Clear site data, unregister the service worker and reload. Old versions can hide new changes.