Setup guide · Astro
Turn an Astro site into an installable PWA (2026)
Complete Astro 4+ recipe for shipping a manifest, service worker and install popup — works with static output and SSR adapters.
Key takeaways
- Astro serves /public verbatim — drop manifest.webmanifest there.
- Register the service worker with a `client:load` script tag on the layout.
- iOS support is manual: detect standalone mode and render the share-sheet guide.
- Use a hosted install popup to avoid writing prompt UI in Astro islands.
Before you start
- Astro 3+
- HTTPS origin
- 192px + 512px icons
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 Astro
- Step 1Place manifest and sw.js in /public
Astro serves these unchanged at the site root.
- Step 2Link the manifest from your base layout
In src/layouts/Layout.astro, add the manifest and theme-color tags.
<link rel="manifest" href="/manifest.webmanifest" /> <meta name="theme-color" content="#111827" /> - Step 3Register the service worker
Add a small inline script inside <head>. Astro will not process it.
<script is:inline> if ('serviceWorker' in navigator) navigator.serviceWorker.register('/sw.js'); </script> - Step 4Ship the install prompt
Drop the InstantPWA snippet into Layout.astro for cross-platform install UI.
<script src="https://instantpwa.com/api/public/embed.js?id=YOUR_ID" async></script>
Minimal sw.js
// public/sw.js
self.addEventListener('install', (e) => self.skipWaiting());
self.addEventListener('activate', (e) => self.clients.claim());
self.addEventListener('fetch', () => {});Common Astro gotchas
- Astro does not bundle files in /public. Do not import sw.js — reference it by URL.
- If you use view transitions, register the worker inside astro:page-load so it survives client-side nav.
FAQ
Do I need a native app if my Astro site is a PWA?
No. Once your Astro site meets the three PWA criteria (HTTPS, a manifest, a service worker), Chromium browsers offer to install it and iOS Safari 16.4+ supports the full standalone experience — including web push.
Will a service worker slow my Astro site down?
Not measurably on first load. The worker installs asynchronously after the page becomes interactive. On repeat visits it typically improves LCP and TTFB because assets are served from cache.
Can I still deploy my Astro site to Vercel, Netlify or Cloudflare?
Yes. Any static or edge host works — the manifest and service worker are plain files served from the origin. No build-time integration is required.
Skip the setup — drop in one line
InstantPWA handles the install prompt across iOS, Android and desktop. Free forever for one popup.
Get started free