Turn a Hugo site into an installable PWA (2026)

Key takeaways

• Hugo copies `static/` verbatim — no build step for PWA files.
• Register the service worker from a small inline script in `head.html`.
• Add the InstantPWA popup for iOS install instructions.

Before you start

• Hugo 0.100+
• HTTPS origin
• Two icon sizes (192 + 512)

manifest.webmanifest

{
  "name": "Your product",
  "short_name": "Product",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#111827",
  "icons": [
    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any maskable" }
  ]
}

Step-by-step for Hugo

1. Step 1
   Drop files in /static

   Create `static/manifest.webmanifest` and `static/sw.js`.

2. Step 2
   Link from your head partial

   Edit `layouts/partials/head.html`.

   <link rel="manifest" href="/manifest.webmanifest" />
   <script>if ('serviceWorker' in navigator) navigator.serviceWorker.register('/sw.js');</script>

3. Step 3
   Add the install popup

   Append the InstantPWA snippet to the same partial.

Minimal sw.js

// public/sw.js
self.addEventListener('install', (e) => self.skipWaiting());
self.addEventListener('activate', (e) => self.clients.claim());
self.addEventListener('fetch', () => {});

Common Hugo gotchas

• Hugo aggressively caches partials — restart `hugo server` after editing head.html.
• If you host on Netlify or Cloudflare Pages, set a `Cache-Control: no-cache` header on `/sw.js` in `_headers`.

FAQ