Progressive Web Apps with Blazor WASM: Complete Implementation Guide

Overview

Service workers, web app manifest, offline support, push notifications, and install prompts for Blazor PWAs.

Web App Manifest

The manifest.json tells browsers how to display your app when installed. Key fields: name, short_name, start_url, display (standalone), theme_color, background_color, and icons.

Use maskable icons so the launcher icon renders correctly on Android's adaptive icon system—without maskable icons, your icon may appear in an awkward circle on some devices.

{
  "name": "My Blazor App",
  "short_name": "MyApp",
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#0066cc",
  "background_color": "#ffffff",
  "icons": [
    { "src": "/icons/favicon.png", "sizes": "192x192", "type": "image/png", "purpose": "any maskable" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any maskable" }
  ]
}

Service Worker Strategies

Cache-First serves assets from cache, falling back to network—ideal for static assets. Network-First checks the network first, falling back to cache—ideal for dynamic API responses.

For Blazor WASM, cache the framework files (which rarely change) with Cache-First and use Network-First for your API calls.

• Cache-First: static assets (JS, CSS, images, WASM)
• Network-First: API calls, user data
• Stale-While-Revalidate: non-critical content
• Network-Only: authentication endpoints, payments

Offline Fallback Page

When the user is offline and requests an uncached route, serve an offline fallback page from the service worker. This should explain the offline state and provide navigation to cached content.

• Cache the offline.html page during SW installation
• Return it for navigate requests when fetch fails
• Show cached content navigation where possible
• Sync queued actions when the connection returns

Key Takeaways

• PWA install prompt requires HTTPS and a valid manifest
• Service worker registration should be deferred until after page load
• Use Workbox to avoid writing service worker boilerplate
• Background sync allows queuing actions for offline retry
• Push notifications require user permission—request at the right moment