Blazor WebAssembly, without the blank first paint

Ship Blazor PWAs that install, update & work offline.

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 from a single script tag.

Get started Try the live playground

dotnet add package Bit.Bswup

1 script tag is the entire wiring

11 lifecycle events your handler can act on

29 documented settings, each with its default

0 third-party dependencies

The problem

A blank page on the first visit, a stale build for days after

A Blazor WebAssembly app has to download a runtime and your assemblies before it can render anything. The standard template hides that behind a blank page, and hides updates behind nothing at all: a new version only takes effect once every tab of your app has been closed.

Situation	Standard Blazor template	With Bswup
First visit	Blank page while the runtime downloads. No indication anything is happening.	A branded splash with an honest progress bar, counting the very bytes the app is waiting on.
Updates	Staged silently, applied only after every tab closes. Users can run a stale build indefinitely.	Downloaded in the background, then announced. The user accepts, and every open tab moves together.
Flaky network	One failed asset fails the whole install. No retries, no reporting.	Retries with backoff, choice of lax or strict tolerance, and structured error payloads.
Install goes wrong	Nothing is watching. A worker killed mid-install leaves the page hanging.	A stall watchdog boots the app from the network instead. A first visit never dead-ends.
Control	Edit the generated worker and hope.	Script attributes, worker settings, lifecycle events, and a JavaScript API.

Where to start

Three steps from installed to shipped

A route through the documentation rather than an index of it.

Get it running

Six small steps from dotnet add package to a working install splash.

Understand the model

Who starts Blazor, how an update is staged, and which requests the worker takes over.

Ship it properly

Hosting headers, sub-path deployments, build-stamped cache versions, custom update banners.

Capabilities

What you get

Every card links to the page that documents it in full.

First-install splash

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

Progress UI

Controlled updates

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

Events & Handler

Offline support

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

Worker settings

Resilient installs

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

errorTolerance

Update polling

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

checkForUpdate()

Configurable, not magical

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

Script options

Durable storage

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

persistStorage()

Clean exit path

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

Backing out

In one paragraph

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.

Architecture

How it fits together

Five pieces, each with one job.

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.

How It Works walks through what each of them does at runtime - the boot handshake, the two lifecycles, and the request pipeline.

Runnable code

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.