Turn a Gatsby site into an installable PWA (2026)

Key takeaways

• `gatsby-plugin-manifest` generates manifest.webmanifest at build time.
• `gatsby-plugin-offline` registers a Workbox service worker automatically.
• iOS Safari still needs a manual install prompt — use InstantPWA.

Before you start

• Gatsby 4+
• HTTPS origin
• 512px source icon

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 Gatsby

1. Step 1
   Install the plugins

   Run `npm i gatsby-plugin-manifest gatsby-plugin-offline`.

2. Step 2
   Configure gatsby-config.js

   Order matters — offline must come after manifest.

   module.exports = {
     plugins: [
       { resolve: 'gatsby-plugin-manifest', options: { name: 'Your app', short_name: 'App', start_url: '/', display: 'standalone', icon: 'src/images/icon.png' } },
       'gatsby-plugin-offline',
     ],
   };

3. Step 3
   Add the install popup

   Inject the InstantPWA snippet via gatsby-ssr.js onRenderBody.

Minimal sw.js

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

Common Gatsby gotchas

• Do not enable offline in `gatsby develop` — it caches stale HTML. Test with `gatsby build && gatsby serve`.
• Purge the CDN when icons change; Gatsby fingerprints assets but not the manifest URL.

FAQ