Convert Webpage to Progressive Web App (PWA): Complete Hugo Website Guide

⬅️ Back to Tutorials

🚀 Quick Start Guide

Want to turn your Hugo website into a Progressive Web App? Here’s the complete process I used to convert TMFNK into a PWA:

  1. Copy site.webmanifest to /static (4 min) - Define your app’s identity and capabilities
  2. Copy sw.js to /static (4 min) - Enable offline functionality and caching
  3. Add meta tags to head-end.html (5 min) - Configure app-like behavior and appearance
  4. Test with Lighthouse (3 min) - Validate functionality and deploy to production

Total Time: ~15 minutes

In case you want or need to uninstall/remove a PWA, here: https://tmfnk.com/use/tutorials/how-to-remove-a-pwa/ is a handy guide

📖 My Journey: Why I Converted TMFNK to a PWA

I converted TMFNK into a PWA to help readers access my blog content even with poor internet connections or when completely offline. As someone who travels frequently and often deals with spotty WiFi (or no internet), I wanted to ensure my content was always accessible.

Challenges I Faced:

  • Documentation Gaps: Many PWA tutorials were either too basic or assumed advanced JavaScript knowledge
  • Hugo Integration: Finding the right way to integrate PWA files with Hugo’s build process
  • Cross-Platform Testing: Ensuring the PWA worked consistently across iOS, Android, and desktop
  • Cache Management: Figuring out optimal caching strategies for my content-heavy blog

Solutions I Implemented:

  • Used Hugo’s static file serving for PWA assets
  • Implemented a simple cache-first strategy with offline fallbacks
  • Added comprehensive error handling and logging
  • Created a version-based cache invalidation system

The result? TMFNK now loads instantly on repeat visits and works offline, providing a much better reading experience for everyone!

📚 Table of Contents

🎯 What is a Progressive Web App?

A Progressive Web App (PWA) is a web application that combines the best of web and mobile apps. It provides:

  • Installability: Users can install your website as an app on their device
  • Offline Functionality: Works without internet connection
  • Native App Experience: App-like interface and behavior
  • Cross-Platform: Works on any device with a modern browser
  • Automatic Updates: No need for app store updates

🛠️ Converting Your Hugo Website to PWA

Follow these steps to convert your Hugo website into a PWA:

1. Create the Web Manifest File

Create a file named site.webmanifest in your /static directory:

{
  "name": "Your Site Name",
  "short_name": "Site Name",
  "description": "Your site description",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#000000",
  "icons": [
    {
      "src": "/android-chrome-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/android-chrome-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

2. Create the Service Worker

Create a file named sw.js in your /static directory:

const CACHE_NAME = "your-site-v1";
const urlsToCache = ["/", "/css/custom.css", "/js/main.js"];

self.addEventListener("install", (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => cache.addAll(urlsToCache))
  );
});

self.addEventListener("fetch", (event) => {
  event.respondWith(
    caches
      .match(event.request)
      .then((response) => response || fetch(event.request))
  );
});

3. Add Meta Tags to HTML Head

In your layouts/_default/baseof.html or create layouts/partials/head-end.html:

<meta name="theme-color" content="#000000" />
<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-status-bar-style" content="default" />
<meta name="apple-mobile-web-app-title" content="Your Site Name" />
<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
<link rel="manifest" href="/site.webmanifest" />

4. Register the Service Worker

Add this script to your base template:

if ("serviceWorker" in navigator) {
  window.addEventListener("load", () => {
    navigator.serviceWorker.register("/sw.js");
  });
}

📱 Installing PWA on Phone and Desktop

Once you’ve set up your PWA, users can install it on their devices:

On Android Phone/Tablet

  1. Open your website in Chrome browser
  2. Tap the menu (three dots) in the top right
  3. Select “Add to home screen” or “Install app”
  4. Confirm by tapping “Add” or “Install”

On iPhone/iPad

  1. Open your website in Safari browser
  2. Tap the share button (square with arrow)
  3. Scroll down and tap “Add to Home Screen”
  4. Confirm by tapping “Add”

On Desktop (Chrome/Edge)

  1. Open your website in the browser
  2. Click the install icon in the address bar (puzzle piece or plus sign)
  3. Or click the menu (three dots) and select “Install [Your Site Name]”
  4. Confirm the installation

Once installed, the PWA appears as a regular app icon and can be launched from the home screen or desktop.

✅ Testing Your PWA

Test your PWA using:

  • Lighthouse: Chrome DevTools > Lighthouse > Generate report (check PWA category)
  • Browser Tools: Check Application tab for manifest and service worker
  • Device Testing: Install and test on various devices

Your PWA should load instantly on repeat visits and work offline!