Blazor Service Worker Update Progress

Ship Blazor PWAs that install, update & work offline - beautifully.

Bswup replaces the default Blazor service worker experience with a real install progress UI, controlled background updates, resilient downloads, and a tiny JavaScript API - all with a single script tag.

Get started Try the live playground

dotnet add package Bit.Bswup

📥

First-install splash

A branded full-screen progress UI while assets download - the very splash this site booted with.

🔄

Controlled updates

Updates download silently in the background and wait for the user to accept - no unprompted reloads, consistent across every open tab.

📴

Offline support

Full precache or lazy passive mode, SPA navigation fallback, media range requests, and external asset caching.

🛡️

Resilient installs

Retries with backoff, lax/strict error tolerance, a first-install stall watchdog, and structured error reporting.

🧭

Update polling

Interval and on-focus update checks, a check-for-update API, and up-to-date / check-failed events.

⚙️

Configurable, not magical

Everything is opt-in via script-tag attributes and service worker settings, with sensible defaults.

💾

Durable storage

One call to request eviction-resistant storage so offline apps survive browser storage pressure.

🧹

Clean exit path

A self-destructing cleanup worker recovers broken clients or removes Bswup entirely from a deployed app.

What is Bswup?

bit Bswup (Blazor service-worker update progress) is a NuGet package for Blazor WebAssembly apps that takes over the service worker lifecycle: it downloads and caches your app's assets with visible progress, verifies their integrity, serves them offline, and manages version updates without ever leaving your users staring at a blank page - or running a stale build for days.

This documentation site is itself a prerendered Blazor WebAssembly app powered by Bswup - open the browser dev tools, go offline, and reload. Then head over to the Live Playground to watch the service worker events in real time.

How it fits together

Piece	What it does
`bit-bswup.js`	Page-side script: registers the service worker, coordinates the install/update handshake, starts Blazor at the right moment, polls for updates, and raises lifecycle events.
`bit-bswup.sw.js`	The service worker engine: precaches assets (with retries and integrity checks), serves fetches from cache, handles SPA navigation fallback, and stages new versions. Imported from your `service-worker.js`.
`bit-bswup.progress.js` + `BswupProgress`	The optional built-in progress UI: splash screen, progress bar, reload button, and failure panel - CSP-friendly and screen-reader aware.
`BitBswup`	A small JavaScript API to check for updates, activate staged versions, request persistent storage, and force-reset a broken client.
`bit-bswup.sw-cleanup.js`	A self-destructing worker to back out of Bswup or recover clients stuck on a broken worker or cache.

Sample projects

Besides this documentation site, the repository ships two runnable samples:

Samples/BasicSample (Bit.Bswup.BasicSample) - a minimal standalone Blazor WebAssembly app with a hand-written handler, deliberately including a failing external asset to exercise the error flow.
Samples/FullSample (Bit.Bswup.FullSample.*) - a Blazor Web App (server + client) using the BswupProgress component with a custom progress bar.