Sorry, there's nothing at this address.
-Backing Out of Bswup
++ Fully remove Bswup from a deployed app - dropping offline support, or recovering clients stuck on a + broken worker or cache - with the self-destructing cleanup worker. +
+ +
+ Replace the content of your service-worker.js and
+ service-worker.published.js (the file deployed builds actually ship, via the
+ ServiceWorker item's PublishedContent mapping) with:
+
What happens next
+On its next update check, every client installs this self-destructing worker instead. It:
+-
+
- activates immediately, +
- purges this app's Bswup and Blazor caches, +
- unregisters its own registration, and +
- signals open tabs to detach. +
+ Tabs the previous worker controlled reload once; everything afterwards runs purely from the network,
+ even while the page keeps referencing bit-bswup.js - each later load just repeats the
+ register/self-unregister cycle silently, with no reloads.
+
bit-bswup.js script tag can be removed from the host document too.
+Client-side reset without backing out
+
+ If you only need to recover a single broken client (not remove Bswup from the deployment),
+ prefer BitBswup.forceRefresh() - it clears this
+ app's caches, unregisters its worker, and reloads, without touching the deployed service worker file.
+
Events & Handler
++ Bswup reports its whole lifecycle through a single global handler function. Use the built-in + progress UI, or write your own handler and drive any markup you like. +
+ +
+ The handler's name is configured through the handler
+ script attribute (default bitBswupHandler). It receives (type, data) where
+ type is one of the BswupMessage constants:
+
Event catalog
+
+
+
+
+
+
+| BswupMessage | Value | Raised when |
|---|---|---|
updateFound | UPDATE_FOUND | The browser found a new service worker version and started installing it. |
stateChanged | STATE_CHANGED | The installing worker's lifecycle state changed (data.currentTarget.state). |
downloadStarted | DOWNLOAD_STARTED | Asset download began. data.version, data.firstInstall. |
downloadProgress | DOWNLOAD_PROGRESS | An asset finished. data.percent (0-100), data.index (1-based count), data.asset (url, reqUrl, hash). |
downloadFinished | DOWNLOAD_FINISHED | All assets are staged. data.firstInstall, data.reload(), data.cleanup(). |
updateReady | UPDATE_READY | A fully staged update is waiting to be activated (data.reload()). |
activate | ACTIVATE | A new version activated (data.version). |
updateNotFound | UPDATE_NOT_FOUND | An update check completed and the app is already on the latest version. |
updateCheckFailed | UPDATE_CHECK_FAILED | An update check itself failed transiently (offline, server hiccup). Non-blocking - the app keeps running. |
error | ERROR | A structured install failure - see below. |
A complete handler
+Finishing a download: reload and cleanup
+-
+
-
+
data.reload()activates the staged version. On a first install it + claims the clients and starts Blazor with no reload; on an update it + performsSKIP_WAITINGand reloads. +
+ -
+
data.cleanup()(optional) asks the active service worker to prune this app's stale + cache buckets right away. It is safe to call at any time - the worker declines while an update is + staged or staging (pruning then happens automatically on activation), and it never touches another + app's caches. Most apps never need it: the same pruning already runs on activation and after every + accepted update. +
+
BswupProgress component's AutoReload parameter
+ defaults to false: when an update finishes downloading, the reload button is shown and the
+ new version activates when the user accepts it - an unprompted reload discards whatever in-page state
+ the user has mid-session. Set AutoReload="true" to restore the old behavior. First
+ installs are unaffected: they always complete the seamless claim-and-start flow (no reload).
+Multi-tab updates
+
+ Service workers are single-instance per origin, so accepting an update in one tab activates the new
+ version for every open tab. When that happens, Bswup has the new worker claim all clients and each
+ other tab reloads itself automatically (via controllerchange) onto the new
+ version. This keeps every tab consistent and avoids the classic failure where an old tab keeps running
+ old app code while its asset requests are served from the new version's cache (mismatched boot config /
+ DLL hashes). The first install is exempt: claiming a client for the first time starts Blazor and does
+ not trigger a reload.
+
The error payload
+Install failures are structured:
+
+
+
+
+
+| Field | Meaning |
|---|---|
reason |
+
+ One of manifest, integrity, fetch,
+ cache, request, install-incomplete,
+ install-aborted, or install-infra (the install died
+ before/while touching CacheStorage - storage pressure, a broken private mode - always
+ fatal).
+ |
+
message | Human-readable description. |
url / hash | The offending asset, when known. |
fatal |
+
+ Whether the install actually stopped. Under the default lax tolerance a
+ failed asset is reported with fatal: false - the install still succeeds and
+ the asset is fetched from the network on first use - so treat it as a warning, not a
+ dead app. fatal: true means no usable staged version is available to this
+ page - though a worker may still have been installed (a lax
+ install-infra failure resolves the install so the worker can keep serving
+ as a network pass-through).
+ |
+
firstInstall |
+
+ Where a fatal failure landed. true: before the app ever booted - Bswup
+ starts the app without a service worker so it still boots. false: a
+ background update failed - the app keeps running on the current version (the
+ previous worker keeps serving).
+ |
+
Getting Started
++ Add install progress, controlled updates, and offline support to a Blazor WebAssembly app + in six small steps. +
+ +1. Install the NuGet package
+2. Enable static file caching (server-hosted apps)
++ Long-lived HTTP caching makes repeat visits and updates dramatically faster - the service worker + revalidates content by hash, so stale HTTP caches are never a correctness problem. +
+3. Defer Blazor's startup
+
+ Bswup must start Blazor at the right moment (after the first install completes, or immediately when
+ the app is already cached), so disable auto-start on the Blazor script in your host document
+ (index.html or App.razor):
+
4. Add the Bswup script
+Reference bit-bswup.js right after the Blazor script:
+ Every attribute is optional - see the Script Options reference for all + of them and their defaults. +
+ +5. Configure the service worker
+
+ Create (or edit) wwwroot/service-worker.js and wwwroot/service-worker.published.js.
+ The only mandatory line is the importScripts call; everything else is tuning:
+
Then make sure the service worker is registered in your project file:
+See the Service Worker Settings reference for every available option.
+ +6. Pick a progress UI
+You have two options:
+-
+
-
+ Use the built-in progress UI - the
BswupProgresscomponent + plusbit-bswup.progress.js- and you are done. This is what this site uses. +
+ - + Write your own handler function and drive any markup you like - see + Events & Handler for the full event catalog and a complete sample. + +
222
+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. +
+ +
+ dotnet add package Bit.Bswup
+
+Hello, world!
+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 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
+
+
+
+
+
-Counter
+| 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. | +
Demo projects
+Besides this documentation site, the repository ships two runnable samples:
+-
+
- Demos/BasicDemo (
Bit.Bswup.BasicDemo) - a minimal standalone Blazor WebAssembly app with a hand-written handler, deliberately including a failing external asset to exercise the error flow.
+ - Demos/FullDemo (
Bit.Bswup.FullDemo.*) - a Blazor Web App (server + client) using theBswupProgresscomponent with a custom progress bar.
+
-
-
- - - - \ No newline at end of file + diff --git a/src/Bswup/Bit.Bswup.Demo/Pages/JsApiPage.razor b/src/Bswup/Bit.Bswup.Demo/Pages/JsApiPage.razor new file mode 100644 index 0000000000..14c5e79668 --- /dev/null +++ b/src/Bswup/Bit.Bswup.Demo/Pages/JsApiPage.razor @@ -0,0 +1,129 @@ +@page "/javascript-api" + +
JavaScript API
+
+ Bswup exposes a small global BitBswup object so you can drive the update lifecycle from
+ your own code - a "check for updates" button, a custom poller, a "reset app" action.
+
BitBswup.checkForUpdate()
+
+ Asks the browser to re-fetch the service worker script and check for a new version. If a new version is
+ found, the normal update flow runs (updateFound → stateChanged →
+ updateReady/downloadFinished). If the app is already on the latest version,
+ Bswup raises updateNotFound so you can stop a spinner or show an "up to date" message.
+
+ If the check itself fails for a transient reason (offline, server hiccup, a throttled background tab),
+ Bswup raises the non-blocking updateCheckFailed event instead of the install-path
+ error event, so the default progress handler does not hide the app or
+ show the install-failed UI; the payload still carries reason/message so you
+ can surface it yourself. Registration-aware and safe to call as often as you like - it is what powers
+ the built-in polling.
+
BitBswup.persistStorage()
+
+ Requests durable, eviction-resistant storage for the origin via navigator.storage.persist()
+ and resolves with a boolean saying whether storage is now persistent. Without it the caches are
+ best-effort and can be reclaimed by the browser (Safari deletes all storage for a site not interacted
+ with for seven days). Calling it from a user gesture - after login, from an "install app" button - has
+ the best chance of being granted. Safe to call repeatedly: an already-persistent origin resolves
+ true without prompting again, and unsupported browsers resolve false with a
+ console warning.
+
BitBswup.skipWaiting()
+
+ If an update has finished downloading and is waiting, this activates it immediately (equivalent to
+ calling the reload callback from updateReady/downloadFinished).
+ Returns true when there was a waiting worker to activate, otherwise false.
+
BitBswup.forceRefresh(cacheFilter?)
++ Clears caches, unregisters the service worker controlling the current page, and reloads. Use this as a + last-resort "reset" when a client gets into a bad state. It only removes this app's own registration - + other apps mounted under different scopes on the same origin are left untouched. +
+
+ By default it clears only the caches this app and Blazor own: the app's scope-qualified Bswup buckets,
+ legacy scope-less buckets, and blazor-resources caches. A sibling Bswup app's scoped
+ buckets are spared, and app-owned CacheStorage buckets (Workbox add-ons, offline app data, cached API
+ responses) are left intact, since those can hold data with no other copy. To change what gets cleared,
+ pass an optional cacheFilter: a string (prefix match), a RegExp, or a
+ predicate (key) => boolean:
+
Polling for updates
++ By default a service worker is only re-checked by the browser on navigation and roughly every 24 hours, + so a tab that stays open for a long time can keep running an old version. There are two ways to check + more often: +
+-
+
-
+ Set
updateInterval(and/or +updateOnVisibility) on the script tag + for built-in polling. Simplest, no extra code - this site uses both. +
+ - Call
BitBswup.checkForUpdate()yourself, from a timer or after a user action:
+
+ Either way, the result surfaces through your handler: a found update flows through
+ updateFound/updateReady, "nothing new" flows through
+ updateNotFound, and a transient check failure flows through
+ updateCheckFailed:
+
updateOnVisibility="true".
+Migrating to v-10-6-0
++ v-10-6-0 is a resilience-focused release. Most changes are internal hardening; this page lists what is + visible when upgrading. +
+ +Action items
+1. Updates no longer auto-reload. BswupProgress.AutoReload now defaults to false - updates announce themselves through the reload button. Set AutoReload="true" to restore the old behavior.
2. Blocked URLs answer 403. prohibitedUrls matches are answered with 403 Forbidden (previously 405). Code detecting a blocked URL by status must check for 403.
3. String entries now take effect. Strings in the URL-matching lists (assetsInclude, assetsExclude, prohibitedUrls, serverHandledUrls, serverRenderedUrls) are now matched literally as substrings. Previous releases silently ignored them - audit any strings sitting in those lists, because they take effect for the first time after upgrading.
4. Hand-written splash markup needs one edit. Move <button id="bit-bswup-reload"> outside the #bit-bswup overlay (and give it a z-index), optionally adding a visually-hidden <span id="bit-bswup-reload-status" role="status"> next to it. The built-in handling no longer reveals the overlay for updates, so a button left inside it would never become visible. The BswupProgress component ships this layout already.
Behavior changes
+-
+
- Cache buckets are scope-qualified:
bit-bswup:<scope-path> - <version>(previouslybit-bswup - <version>). Multiple Bswup apps on one origin no longer evict each other's caches; the migration from legacy-named buckets is automatic and does not re-download.
+ - Under the default
laxtolerance, the asset download now runs inside the install event (waitUntil): the browser keeps the worker alive for the whole download, andupdateReadyis only raised once the new version is fully staged - previously it could fire while the download had barely started.
+ assetsUrldefaults to a path resolved against the service worker script's own location (previously root-absolute), so apps mounted on a sub-path work without configuration.
+ - The
cleanupcallback only prunes when no update is staged or staging, andBitBswup.forceRefresh()'s default filter clears only this app's own, legacy, and Blazor caches. The same staged-or-staging guard protects every cache-pruning path, so a prune can never race a newer install's freshly written bucket.
+ - Requests carrying a
Rangeheader are answered with real206 Partial Contentslices from cached bodies (cached media now plays in Safari), and partial responses are never written to the cache.
+ - Updates found later in the same session as the first install are treated as real updates:
updateReadyis raised,downloadFinishedcarriesfirstInstall: false, and accepting them runs the normalSKIP_WAITINGflow. Previously a long-lived tab kept classifying every later update as another first install.
+ - Navigations whose URL is itself a managed asset (e.g. opening
/manifest.jsondirectly) are served that asset instead of the SPA default document.
+ - An update's re-download of the default document and of hash-less assets no longer deletes the existing cache entry first: if the refresh fails (offline mid-update), the previous copy keeps serving - including offline navigation. +
- The built-in progress UI stays out of the way during background updates: the full-screen splash is first-install only (
downloadStarted/downloadProgresspayloads carryfirstInstallso custom handlers can do the same), the reload button lives outside the overlay, it is announced via arole="status"region, and the overlay no longer swallows clicks outside its content.
+ - A first install completes even when no handler function is registered at all (previously the app waited out the full
stallTimeoutbehind the splash).
+ - The cleanup worker unregisters its own registration during teardown and no longer claims clients; the page reloads on
UNREGISTERonly while actually controlled, removing a reload-loop hazard.
+ - The passive-mode background top-up after first boot is deterministic: it fills every asset still missing from the cache. +
- The default asset excludes cover all shipped worker-script variants (
bit-bswup.sw.min.js,bit-bswup.sw-cleanup.js,bit-bswup.sw-cleanup.min.js).
+ - A manifest or
externalAssetsentry whose URL cannot be parsed is skipped with a non-fatalrequesterror instead of killing the whole service worker at startup.
+ - A navigation to a URL that only a
RegExpexternalAssets pattern matches is served the app shell, never the pattern asset - and a shell cache miss during navigation is refilled from the shell's own URL, never from the navigated route's URL.
+ WAITING_SKIPPEDandUNREGISTERnever reload an uncontrolled page anymore; they make sure the app is booted instead. Activating a first install throughBitBswup.skipWaiting()completes the seamless claim-and-start flow instead of reloading.
+ - A page that loads while an update is already mid-install now observes it:
updateReady/stateChangedfire in that tab when the update finishes staging.
+ - An exception thrown by the app's
bitBswupHandlerno longer breaks the update pipeline (it is logged, and the remaining messages still dispatch).
+
New capabilities
+-
+
- Update polling: the
updateInterval/updateOnVisibilityscript attributes, a registration-awareBitBswup.checkForUpdate(), and theupdateNotFound/updateCheckFailedevents.
+ - Install robustness:
errorTolerance(lax/strict), transient-failure retries (maxRetries,retryDelay), thestallTimeoutfirst-install watchdog, and structurederrorpayloads (reason,fatal,firstInstall- including the terminalinstall-infrareason).
+ - Storage:
persistStorage/BitBswup.persistStorage()for eviction-resistant storage, andcacheVersionfor manual control of cache-bucket rotation.
+ - Registration: automatic retry with the default scope when the browser rejects the configured
scope, and fingerprint-tolerant Blazor entry-script detection for .NET 9+@@Assets[...]references.
+
+
+
+
+
+
+
diff --git a/src/Bswup/Bit.Bswup.Demo/Pages/ProgressUIPage.razor b/src/Bswup/Bit.Bswup.Demo/Pages/ProgressUIPage.razor
new file mode 100644
index 0000000000..861f5d67ab
--- /dev/null
+++ b/src/Bswup/Bit.Bswup.Demo/Pages/ProgressUIPage.razor
@@ -0,0 +1,150 @@
+@page "/progress-ui"
+
+Live Playground
++ This documentation site is itself a Blazor WebAssembly app powered by Bswup. Inspect its service + worker, drive the JavaScript API, and watch every lifecycle event + arrive in real time. +
+ ++ Open dev tools → Network and switch to Offline, then reload - the app keeps working from + cache. Or open this site in a second tab, accept an update there, and watch this tab reload + itself onto the new version. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Service worker status
+-
+
- Service worker
- …
- This page
- …
- Scope
- …
- Active worker
- …
- Update staged
- …
- Storage
- …
+
+
+ Cache buckets
+
+ Bswup's buckets are scope-qualified:
+ bit-bswup:<scope-path> - <version>.
+
Update lifecycle
+
+ checkForUpdate() re-fetches the service worker script; if nothing changed you
+ will see UPDATE_NOT_FOUND in the log below. skipWaiting()
+ activates a staged update immediately.
+
+
+
+
+ Storage & reset
+
+ persistStorage() requests eviction-resistant storage (browsers may prompt or
+ apply engagement heuristics). forceRefresh() clears this app's caches,
+ unregisters its worker, and reloads - the last-resort client reset.
+
+
+
+
+ Event log
+
+ Every BswupMessage raised on this page - fed by a custom handler chained after the
+ built-in progress UI via the Handler/data-bit-bswup-handler option
+ (newest first, capped at 200 entries).
+
The Built-in Progress UI
+
+ Instead of writing a handler yourself, use the built-in splash/progress UI: the
+ BswupProgress Razor component (the markup) plus bit-bswup.progress.js
+ (the behavior). It registered the splash you saw when this site first installed.
+
Reference both in your host document:
+Then render the component:
+Component parameters
+
+ Each parameter maps to a data-bit-bswup-* attribute that the script reads at load time.
+ The component emits no inline <script>, so it works under a strict
+ Content-Security-Policy and when rendered by an interactive Blazor renderer.
+
+
+
+
+
+
+| Parameter | Default | Description |
|---|---|---|
AutoReload | false | Reload automatically when an update finishes instead of showing the reload button. Changed in v-10-6-0 - previously defaulted to true. |
ShowLogs | false | Log lifecycle messages to the console. |
ShowAssets | false | List each downloaded asset inside the splash. |
AppContainer | #app | Selector of the element to hide while installing (used with HideApp). An invalid selector is tolerated - only the hiding is skipped. |
HideApp | false | Hide the app container while the first install downloads. |
AutoHide | false | Hide the splash automatically when the download finishes. |
Handler | - | Name of an additional custom handler invoked after the built-in handling, so you can layer your own behavior without replacing the UI. (Do not point it at bitBswupHandler itself - self-references are detected and ignored.) |
ChildContent | - | Replaces the default splash markup with your own - see below. |
Behavior worth knowing
+-
+
-
+ The full-screen splash is first-install only. A background update downloads
+ silently behind the running app; when it finishes - or when an update is already staged at page
+ load - the reload button appears on its own, with a screen-reader announcement through a
+
role="status"region. +
+ - + Clicks outside the splash content pass through the overlay, so an app force-started under a failure + panel stays usable. + +
- + A failure panel with retry appears for fatal first-install errors; deterministic failures + (an unparseable manifest, an integrity mismatch) hide the retry button since reloading would fail + identically. + +
-
+ Runtime toggles are available via
+
BitBswupProgress.config({ autoReload, showLogs, showAssets, hideApp, autoHide }). +
+
Custom splash content
+
+ Pass ChildContent to replace the default splash markup. The component keeps initializing
+ automatically, and the built-in behavior drives your markup through the documented element ids -
+ include whichever you want driven:
+
+
+
+
+
+| Element id | Driven as |
|---|---|
bit-bswup-progress-bar | Width + aria-valuenow set to the download percentage; the splash root also gets --bit-bswup-percent / --bit-bswup-percent-text CSS variables. |
bit-bswup-percent | Text content set to NN%. |
bit-bswup-assets | Each downloaded asset prepended as a list item. |
bit-bswup-error (+ -message, -details, -retry) | The failure panel for fatal first-install errors. |
bit-bswup-reload / bit-bswup-reload-status | The update-ready button and its screen-reader status region. |
#bit-bswup-reload) and its status region are always rendered by
+ the component itself, outside the overlay, even with custom content - they are the only way a
+ finished update surfaces under the default AutoReload="false". A custom splash should not
+ render its own copy of those two; restyle them by id instead.
+Standalone WebAssembly apps (like this site)
+
+ In a standalone Blazor WebAssembly app the splash must exist before Blazor starts - on a first
+ install, Blazor only boots after the download completes - so the BswupProgress component
+ (which renders as part of the app) cannot paint the first-install splash. Hand-write the same markup in
+ index.html instead; bit-bswup.progress.js self-initializes from the
+ data-bit-bswup-* attributes exactly as it does for the component:
+
#bit-bswup-reload and its status region outside the #bit-bswup
+ overlay (a finished background update must surface the button without revealing the splash), and give
+ the button its own z-index if your app has fixed chrome in the top-right corner. View the
+ source of this very page for a complete working example.
+
+
+
+
+";
+}
diff --git a/src/Bswup/Bit.Bswup.Demo/Pages/ScriptOptionsPage.razor b/src/Bswup/Bit.Bswup.Demo/Pages/ScriptOptionsPage.razor
new file mode 100644
index 0000000000..5876bbdaf0
--- /dev/null
+++ b/src/Bswup/Bit.Bswup.Demo/Pages/ScriptOptionsPage.razor
@@ -0,0 +1,175 @@
+@page "/script-options"
+
+
+
+Installing the app
+
+
+
+ 0%
+
+
+ Update failed to install
+ + + +Script Options
+
+ Every option of the bit-bswup.js script tag. All of them are optional - remove any
+ attribute to fall back to its default.
+
Quick reference
+
+
+
+
+
+
+| Attribute | Default | Summary |
|---|---|---|
scope | / | Service worker scope; also namespaces the cache buckets. |
log | warn | Log level: none, error, warn, info, verbose, debug. |
sw | service-worker.js | Path of the service worker file. |
handler | bitBswupHandler | Name of the global function receiving lifecycle events. |
blazorScript | auto-detected | Path of the Blazor entry script, when it lives at a non-default path. |
updateInterval | 0 (off) | Seconds between automatic update checks. |
updateOnVisibility | false | Check for an update whenever the tab returns to the foreground. |
stallTimeout | 60 | Seconds of total service worker silence before a first install falls back to a network boot. |
persistStorage | false | Request eviction-resistant storage at startup. |
options | bitBswup | Name of a global object to read all of these settings from. |
scope
+
+ The scope of the service worker. Defaults to /. A service worker can only control URLs
+ beneath its own folder unless the server sends a Service-Worker-Allowed header, so if
+ your app is mounted on a sub-path (e.g. https://host/myapp/) set this to that sub-path.
+
+ If the browser refuses the configured scope, Bswup automatically retries with the default scope - + the folder containing the service worker script - so the app keeps offline support rather than losing + the service worker entirely; the fallback is reported as a console warning. +
+bit-bswup:<scope-path> - <version>,
+ so several Bswup apps mounted under different scopes on one origin keep fully independent caches.
+ The previous scope-less name made sibling apps evict each other's caches on every update. On upgrade,
+ entries from a legacy-named bucket are migrated without re-downloading.
+log
+
+ The log level of the Bswup logger. Available options: none, error,
+ warn, info, verbose, and debug. Each level
+ includes everything above it (e.g. info also shows warn and
+ error). Defaults to warn; use none to silence all output.
+
sw
+The file path of the service worker file. Defaults to service-worker.js.
handler
+
+ The name of the global handler function for service worker events. Defaults to
+ bitBswupHandler - which is also the name the built-in progress script registers, so the
+ two wire up without configuration. The handler is re-resolved until found, so it may be registered
+ after bit-bswup.js loads.
+
blazorScript
+
+ The path of the Blazor entry-point script (the one you added autostart="false" to).
+ When omitted, Bswup auto-detects both the Blazor Web App script (_framework/blazor.web.js)
+ and the standalone Blazor WebAssembly script (_framework/blazor.webassembly.js), so you
+ only need to set this if your script lives at a non-default path.
+
+ Matching is fingerprint-tolerant: the fingerprinted names .NET 9+ emits when the script is referenced
+ through @@Assets["..."] / the ImportMap (e.g. _framework/blazor.web.<fingerprint>.js)
+ are recognized automatically, both for the auto-detected defaults and for an explicitly configured value.
+
updateInterval
+
+ Number of seconds between automatic update checks. By default the browser only re-checks the service
+ worker on navigation and roughly every 24 hours, so a long-lived SPA tab can run a stale version for a
+ long time. Set a positive number (e.g. 3600 for hourly) to have Bswup call
+ reg.update() on a timer. Checks are skipped while the tab is in the background and resume
+ when it becomes visible again. Omit or set 0 to disable (the default).
+
updateOnVisibility
+
+ When true, Bswup checks for an update every time the tab returns to the foreground (the
+ visibilitychange event) - a lightweight way to catch updates right when a user comes back
+ to a tab they left open. Disabled by default.
+
stallTimeout
++ Number of seconds of complete service worker silence (no message, no lifecycle event) after + which, on a first install only, Bswup stops waiting and starts Blazor directly from + the network. This is the last line of defense against install failures that report nothing - most + notably the browser terminating the service worker mid-install (Chromium kills installs after + ~5 minutes) - which would otherwise leave the app frozen behind the splash forever. +
+
+ The page is uncontrolled at that point, so it behaves exactly as if no service worker existed, and the
+ install is retried on the next load. Every progress message resets the timer, so a slow-but-healthy
+ download never triggers it - only true silence does. Defaults to 60; set 0
+ to disable. Updates are unaffected: the app is already running when an update stalls.
+
persistStorage
+
+ When true, Bswup asks the browser to make the origin's storage persistent
+ (navigator.storage.persist()) at startup. By default everything Bswup caches lives in
+ best-effort storage: browsers silently reclaim it under disk pressure, and Safari deletes
+ all storage for a site that has not been interacted with for seven days - the user
+ comes back offline to an app that no longer boots. Persistent storage exempts the origin from that
+ eviction.
+
BitBswup.persistStorage() yourself from a user
+ gesture - after login, or from an "install app" button.
+options
+
+ The name of a global configuration object to read settings from. Defaults to bitBswup.
+ Every option above can also be supplied as a property of that object; the object is merged over the
+ built-in defaults first, and any script-tag attribute then overrides the matching property. This is
+ the way to configure Bswup when the script is injected dynamically, where attribute-based
+ configuration may not be readable.
+
Service Worker Settings
+
+ Everything you can configure in service-worker.js before importing the Bswup engine.
+
+ The most important line is the last one - the only mandatory config in this file: +
+
+ Unlike the assets in service-worker-assets.js (which Bswup verifies with Subresource
+ Integrity), the service worker script itself cannot be integrity-pinned: browsers support neither an
+ integrity option on register() nor SRI for importScripts().
+ A tampered service-worker.js or bit-bswup.sw.js is effectively persistent,
+ fully-privileged XSS. Serve both over HTTPS from an origin you control and apply a strict
+ Content-Security-Policy.
+
+ Bswup registers with updateViaCache: 'none' so update checks bypass the HTTP cache for
+ the whole service-worker.js → bit-bswup.sw.js → service-worker-assets.js
+ import chain. As defense-in-depth (support is uneven on older Safari/iOS, and proxies are not bound
+ by it), also send Cache-Control: no-cache for these two files so every fetch
+ revalidates against the origin.
+
How the URL-matching lists are matched
+
+ assetsInclude, assetsExclude, prohibitedUrls,
+ serverHandledUrls and serverRenderedUrls all accept the same two kinds of entry:
+
-
+
- a
RegExp(e.g./\/admin\//) is used as the pattern it is - what you want for anything non-trivial;
+ - a string (e.g.
'/admin/') is matched literally as a substring of the URL. It is regex-escaped, so'v1.0'matches onlyv1.0and neverv1X0.
+
'app.css' matches /css/app.css anywhere in the URL; anchor with a
+ RegExp such as /\/app\.css$/ if that is too broad. Prefer a RegExp
+ whenever you need anchoring, alternation or wildcards. Also note: before v-10-6-0 string entries were
+ silently ignored - see the migration guide.
+Asset selection
+ +assetsInclude
+The list of file names from the assets list to include when Bswup stores them in cache storage (regex supported).
+ +assetsExclude
+The list of file names from the assets list to exclude when Bswup stores them in cache storage (regex supported).
+ +ignoreDefaultInclude / ignoreDefaultExclude
+Ignore the default include / exclude arrays Bswup provides. The defaults are:
+
+ /\.wasm/, /\.pdb/ and /\.html/ are deliberately unanchored
+ (mirroring the standard Blazor template), so variants such as foo.wasm.br also match.
+ The default excludes keep the service worker's own scripts out of the cache:
+
externalAssets
+
+ The list of external assets to cache that are not included in the auto-generated assets file. For
+ example, if you're not using index.html (like _host.cshtml), add
+ { "url": "/" }.
+
Accepted entry shapes and behaviors:
+-
+
- An object with a
url(a concrete string, or aRegExpfor server-generated names unknown ahead of time), a bare string, or a bareRegExp; a single value also works without the array.
+ - An entry may carry a
hash(an SRI digest,sha256-...) that participates in?v=cache busting and - whenenableIntegrityCheckis on - in integrity verification, exactly like a manifest asset.
+ - Entries whose
urlcannot be parsed are skipped with a non-fatalrequesterror instead of breaking the worker.
+ - Cross-origin entries are fetched in CORS mode first; when the host sends no CORS headers, Bswup retries with
no-corsand caches the resulting opaque response so the asset still works offline. This fallback is skipped for integrity-checked assets. Browsers pad opaque responses in quota accounting (Chromium reserves several megabytes per entry), so prefer CORS-enabled hosts when you control them.
+ - Media works too: requests carrying a
Rangeheader are answered with a real206 Partial Contentsliced from the cached full body (Safari refuses media served as200for a ranged request); uncached ranged requests pass through with theirRangeintact, and partial responses are never written to the cache.
+ - Entries cached for
RegExppatterns are kept across updates so the app still boots offline, but only the newest three generations per pattern survive each update.
+
Navigation & URLs
+ +defaultUrl
+
+ The default page URL, served from cache for navigation requests (the SPA fallback). Defaults to
+ index.html; use / when using _Host.cshtml. The value must match
+ an entry that actually exists in service-worker-assets.js or externalAssets;
+ the comparison uses resolved URLs, so equivalent spellings match. When nothing matches,
+ offline navigation cannot work and Bswup logs a defaultUrl ... matches no asset warning
+ at startup.
+
-
+
- Navigations whose URL is itself a managed asset are served that asset instead of the default document (changed in v-10-6-0): opening
/manifest.jsondirectly shows that file, while route URLs (/counter, ...) still get the app shell.
+ - If your host answers the shell URL with a redirect (e.g.
/→/index.html, common on Cloudflare Pages and Netlify), Bswup rebuilds that response so offline deep-link navigation keeps working instead of failing with a redirect-mode error.
+
assetsUrl
+
+ The path of the compile-time assets manifest (default file name service-worker-assets.js).
+ The default is resolved relative to the service worker script's own location - which is also where
+ Blazor publishes the file - so it works unchanged for apps mounted on a sub-path. Set it explicitly
+ only when the file lives somewhere else; a leading / makes the path origin-absolute.
+
prohibitedUrls
+
+ URLs that should not be accessed (regex supported). Matching requests are answered by the service
+ worker with 403 Forbidden for every HTTP method (changed in v-10-6-0 - previously
+ 405).
+
serverHandledUrls
+URLs that skip the service worker offline pipeline entirely and are handled only by the server (regex supported) - e.g. /api, /swagger.
serverRenderedUrls
+URLs that should be rendered by the server rather than the client while navigating (regex supported) - e.g. /about.html, /privacy.
caseInsensitiveUrl
+
+ Enables case-insensitive URL checking - for asset cache matching and every URL-matching regex
+ list: when enabled, patterns are compiled with the i flag so e.g.
+ prohibitedUrls: [/\/admin\//] also blocks /ADMIN/.
+
noPrerenderQuery
+
+ The query string attached to the default document request to disable server prerendering, so an
+ unwanted prerendered result is not cached - e.g. no-prerender=true.
+
forcePrerender
++ Forces prerendering of the default document for every navigation request to ensure the server always + has the latest version of the app. Useful for server-rendered apps. +
+ +Install behavior & resiliency
+ +isPassive
++ Enables passive mode: assets are not cached in advance but upon first request. Passive mode does not + skip the full download entirely - on a first install, once Blazor has started, the service + worker still tops up the cache in the background with every asset not yet fetched, so the app ends up + fully offline-capable. What passive mode buys is that the first paint is never blocked behind a full + precache. Assets lazily fetched by the app while the top-up runs can be downloaded twice in that + window - a bandwidth cost, not a correctness issue. +
+ +errorTolerance
+Controls how the service worker reacts to asset download / cache failures during install:
+
+
+
+
+
+
+| Value | Behavior |
|---|---|
lax (default) |
+
+ Best-effort install. Asset failures never fail the install; missing assets are filled in
+ lazily on first fetch. Failures are reported through the error event with
+ fatal: false and still count toward progress so the bar reaches 100%.
+ Tolerates optional externalAssets that may legitimately 404, and avoids
+ leaving a first visit with no service worker to complete the startup handshake. The
+ download runs under the install event's waitUntil, so
+ updateReady is only announced once the background fill has settled.
+ |
+
strict |
+
+ Mirrors the standard Microsoft template / Workbox behavior. If any required asset fails,
+ the install rejects, the partial cache is discarded, and the previous service worker (if
+ any) keeps serving. Failed assets are not counted toward progress, so 100% means
+ every asset succeeded; the abort is reported with reason: 'install-aborted'
+ and fatal: true. On a first install (no previous version to fall back to)
+ Bswup starts the app without a service worker so it still boots, and the install is
+ retried on the next load.
+ |
+
maxRetries / retryDelay
+
+ maxRetries (default 2) is the number of additional download attempts
+ after the first when an asset fails transiently during install (a rejected fetch, or HTTP 408/429/5xx).
+ Deterministic failures - 404/403 and other permanent statuses, and SRI mismatches - are never retried,
+ since identical bytes would fail identically.
+
+ retryDelay (default 300) is the base backoff in milliseconds: attempt
+ n waits retryDelay * 2^(n-1) plus random jitter, so a mass failure doesn't re-hit
+ the origin in one synchronized burst.
+
enableIntegrityCheck
+
+ Enables the browsers' built-in integrity verification by setting the integrity attribute
+ on the requests the service worker creates to fetch assets.
+
Caching & updates
+ +cacheVersion
+
+ Overrides the value used to name the cache bucket (bit-bswup:<scope-path> - <version>).
+ By default this tracks Blazor's assetsManifest.version (a hash over the published assets),
+ so the cache rotates automatically whenever any asset hash changes - and only then. Set it to take
+ manual control:
+
-
+
- Pin it to a stable string so noisy dev rebuilds don't needlessly evict the whole cache. +
- Bump it to force a refresh when a meaningful change lives outside Blazor's asset manifest. +
- Feed it a build-stamped value (commit SHA, build timestamp) so it bumps automatically per publish. +
+ Only the cache bucket name is affected: per-asset ?v= cache busting and Subresource
+ Integrity keep using each asset's own hash.
+
disableHashlessAssetsUpdate
++ Disables the automatic re-download of hash-less assets (e.g. external assets) that Bswup performs every + time an update is found. +
+ +enableCacheControl
+
+ Adds cache-busting to each asset request (cache: 'no-store' plus a
+ cache-control: no-cache header). The header is only attached to same-origin requests: it
+ is not CORS-safelisted, so on a cross-origin asset it would force a preflight most third-party hosts
+ reject; cross-origin requests rely on the cache: no-store option alone.
+
Diagnostics
+-
+
enableDiagnostics: pushes service worker logs to the browser console.
+ enableFetchDiagnostics: additionally logs every fetch event the worker handles.
+
Modes
+
+ A mode is a preset bundle of defaults for the individual settings above
+ (isPassive, defaultUrl, forcePrerender,
+ errorTolerance, caseInsensitiveUrl, noPrerenderQuery): it only
+ fills settings you have not assigned yourself, so any explicit assignment always wins over the preset -
+ including explicit falsy values such as caseInsensitiveUrl = false.
+
+
+
+
+
+
+
+
+@code {
+ private const string FullConfigCode = @"self.assetsInclude = [/\/data\.db$/];
+self.assetsExclude = [/\.scp\.css$/, /weather\.json$/];
+self.defaultUrl = '/';
+self.prohibitedUrls = [/\/admin\//];
+self.serverHandledUrls = [/\/api\//];
+self.serverRenderedUrls = [/\/privacy$/];
+self.externalAssets = [
+ {
+ ""url"": ""/""
+ },
+ {
+ ""url"": ""https://www.googletagmanager.com/gtag/js?id=G-G123456789""
+ }
+];
+self.assetsUrl = '/service-worker-assets.js';
+self.noPrerenderQuery = 'no-prerender=true';
+self.cacheVersion = '2026.05.31-abc1234';
+
+self.caseInsensitiveUrl = true;
+self.ignoreDefaultInclude = true;
+self.ignoreDefaultExclude = true;
+self.isPassive = true;
+self.enableIntegrityCheck = true;
+self.enableDiagnostics = true;
+self.enableFetchDiagnostics = true;
+
+self.importScripts('_content/Bit.Bswup/bit-bswup.sw.js');";
+
+ private const string DefaultIncludeCode = @"[/\.dll$/, /\.wasm/, /\.pdb/, /\.html/, /\.js$/, /\.json$/, /\.css$/, /\.woff$/, /\.png$/,
+ /\.jpe?g$/, /\.gif$/, /\.ico$/, /\.blat$/, /\.dat$/, /\.svg$/, /\.woff2$/, /\.ttf$/, /\.webp$/]";
+
+ private const string DefaultExcludeCode = @"[
+ /^_content\/Bit\.Bswup\/bit-bswup\.sw\.js$/,
+ /^_content\/Bit\.Bswup\/bit-bswup\.sw\.min\.js$/,
+ /^_content\/Bit\.Bswup\/bit-bswup\.sw-cleanup\.js$/,
+ /^_content\/Bit\.Bswup\/bit-bswup\.sw-cleanup\.min\.js$/,
+ /^service-worker\.js$/,
+]";
+
+ private const string ExternalAssetsCode = @"self.externalAssets = [
+ { ""url"": ""/"" }, // the host page itself (e.g. _host.cshtml)
+ ""https://fonts.example.com/app-font.woff2"", // bare string shorthand
+ { ""url"": /_framework\/resource-collection\..*\.js/ }, // RegExp for server-generated names
+ { ""url"": ""/lib/chart.js"", ""hash"": ""sha256-..."" } // with SRI hash (cache busting + integrity)
+];";
+}
diff --git a/src/Bswup/Bit.Bswup.Demo/Properties/launchSettings.json b/src/Bswup/Bit.Bswup.Demo/Properties/launchSettings.json
index 8093b9bbbe..e4eff42357 100644
--- a/src/Bswup/Bit.Bswup.Demo/Properties/launchSettings.json
+++ b/src/Bswup/Bit.Bswup.Demo/Properties/launchSettings.json
@@ -1,4 +1,4 @@
-{
+{
"$schema": "http://json.schemastore.org/launchsettings.json",
"profiles": {
"Bit.Bswup.Demo": {
@@ -6,10 +6,10 @@
"dotnetRunMessages": true,
"launchBrowser": true,
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
- "applicationUrl": "http://localhost:5020;https://localhost:5021",
+ "applicationUrl": "http://localhost:5024;https://localhost:5025",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
-}
\ No newline at end of file
+}
diff --git a/src/Bswup/Bit.Bswup.Demo/Shared/Callout.razor b/src/Bswup/Bit.Bswup.Demo/Shared/Callout.razor
new file mode 100644
index 0000000000..e1f393e632
--- /dev/null
+++ b/src/Bswup/Bit.Bswup.Demo/Shared/Callout.razor
@@ -0,0 +1,19 @@
+| Mode | Behavior |
|---|---|
NoPrerender | Disables prerendering of the default document for every navigation request. |
InitialPrerender | Enables prerendering of the default document only for the initial navigation request. |
AlwaysPrerender | Enables prerendering of the default document for every navigation request. |
FullOffline | Full offline mode: all assets are cached and served from cache from the first time the app loads. |
+
+
+@code {
+ /// @(Title ?? DefaultTitle)
+ @ChildContent
+
+
+
+@code {
+ [Parameter] public string Code { get; set; } = string.Empty;
+ [Parameter] public string Language { get; set; } = "code";
+}
diff --git a/src/Bswup/Bit.Bswup.Demo/Shared/MainLayout.razor b/src/Bswup/Bit.Bswup.Demo/Shared/MainLayout.razor
new file mode 100644
index 0000000000..a9aff959b2
--- /dev/null
+++ b/src/Bswup/Bit.Bswup.Demo/Shared/MainLayout.razor
@@ -0,0 +1,34 @@
+@inherits LayoutComponentBase
+
+
+ @Language
+
+
+ @Code.Trim('\r', '\n')
+ bit Bswup
+
+ v10.5.0
+
+ NuGet
+ GitHub
+
+
-
-
-
-
-
diff --git a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/wwwroot/app.css b/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/wwwroot/app.css
deleted file mode 100644
index e398853b8e..0000000000
--- a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/wwwroot/app.css
+++ /dev/null
@@ -1,29 +0,0 @@
-h1:focus {
- outline: none;
-}
-
-.valid.modified:not([type=checkbox]) {
- outline: 1px solid #26b050;
-}
-
-.invalid {
- outline: 1px solid #e50000;
-}
-
-.validation-message {
- color: #e50000;
-}
-
-.blazor-error-boundary {
- background: url(data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iNTYiIGhlaWdodD0iNDkiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIG92ZXJmbG93PSJoaWRkZW4iPjxkZWZzPjxjbGlwUGF0aCBpZD0iY2xpcDAiPjxyZWN0IHg9IjIzNSIgeT0iNTEiIHdpZHRoPSI1NiIgaGVpZ2h0PSI0OSIvPjwvY2xpcFBhdGg+PC9kZWZzPjxnIGNsaXAtcGF0aD0idXJsKCNjbGlwMCkiIHRyYW5zZm9ybT0idHJhbnNsYXRlKC0yMzUgLTUxKSI+PHBhdGggZD0iTTI2My41MDYgNTFDMjY0LjcxNyA1MSAyNjUuODEzIDUxLjQ4MzcgMjY2LjYwNiA1Mi4yNjU4TDI2Ny4wNTIgNTIuNzk4NyAyNjcuNTM5IDUzLjYyODMgMjkwLjE4NSA5Mi4xODMxIDI5MC41NDUgOTIuNzk1IDI5MC42NTYgOTIuOTk2QzI5MC44NzcgOTMuNTEzIDI5MSA5NC4wODE1IDI5MSA5NC42NzgyIDI5MSA5Ny4wNjUxIDI4OS4wMzggOTkgMjg2LjYxNyA5OUwyNDAuMzgzIDk5QzIzNy45NjMgOTkgMjM2IDk3LjA2NTEgMjM2IDk0LjY3ODIgMjM2IDk0LjM3OTkgMjM2LjAzMSA5NC4wODg2IDIzNi4wODkgOTMuODA3MkwyMzYuMzM4IDkzLjAxNjIgMjM2Ljg1OCA5Mi4xMzE0IDI1OS40NzMgNTMuNjI5NCAyNTkuOTYxIDUyLjc5ODUgMjYwLjQwNyA1Mi4yNjU4QzI2MS4yIDUxLjQ4MzcgMjYyLjI5NiA1MSAyNjMuNTA2IDUxWk0yNjMuNTg2IDY2LjAxODNDMjYwLjczNyA2Ni4wMTgzIDI1OS4zMTMgNjcuMTI0NSAyNTkuMzEzIDY5LjMzNyAyNTkuMzEzIDY5LjYxMDIgMjU5LjMzMiA2OS44NjA4IDI1OS4zNzEgNzAuMDg4N0wyNjEuNzk1IDg0LjAxNjEgMjY1LjM4IDg0LjAxNjEgMjY3LjgyMSA2OS43NDc1QzI2Ny44NiA2OS43MzA5IDI2Ny44NzkgNjkuNTg3NyAyNjcuODc5IDY5LjMxNzkgMjY3Ljg3OSA2Ny4xMTgyIDI2Ni40NDggNjYuMDE4MyAyNjMuNTg2IDY2LjAxODNaTTI2My41NzYgODYuMDU0N0MyNjEuMDQ5IDg2LjA1NDcgMjU5Ljc4NiA4Ny4zMDA1IDI1OS43ODYgODkuNzkyMSAyNTkuNzg2IDkyLjI4MzcgMjYxLjA0OSA5My41Mjk1IDI2My41NzYgOTMuNTI5NSAyNjYuMTE2IDkzLjUyOTUgMjY3LjM4NyA5Mi4yODM3IDI2Ny4zODcgODkuNzkyMSAyNjcuMzg3IDg3LjMwMDUgMjY2LjExNiA4Ni4wNTQ3IDI2My41NzYgODYuMDU0N1oiIGZpbGw9IiNGRkU1MDAiIGZpbGwtcnVsZT0iZXZlbm9kZCIvPjwvZz48L3N2Zz4=) no-repeat 1rem/1.8rem, #b32121;
- padding: 1rem 1rem 1rem 3.7rem;
- color: white;
-}
-
- .blazor-error-boundary::after {
- content: "An error has occurred."
- }
-
-.darker-border-checkbox.form-check-input {
- border-color: #929292;
-}
diff --git a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/wwwroot/service-worker.js b/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/wwwroot/service-worker.js
deleted file mode 100644
index 476267b680..0000000000
--- a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/wwwroot/service-worker.js
+++ /dev/null
@@ -1,49 +0,0 @@
-// bit version: 10.5.0
-
-// In development, always fetch from the network and do not enable offline support.
-// This is because caching would make development more difficult (changes would not
-// be reflected on the first load after each change).
-//self.addEventListener('fetch', () => { });
-
-self.assetsInclude = [];
-self.assetsExclude = [
- /Bit\.Bswup\.NewDemo\.Client\.styles\.css$/
-];
-self.defaultUrl = '/';
-self.prohibitedUrls = [];
-self.assetsUrl = '/service-worker-assets.js';
-
-// more about SRI (Subresource Integrity) here: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
-// online tool to generate integrity hash: https://www.srihash.org/ or https://laysent.github.io/sri-hash-generator/
-// using only js to generate hash: https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest
-self.externalAssets = [
- {
- "url": "/"
- },
- {
- "url": "app.css"
- },
- {
- "url": "_framework/blazor.web.js?v=10.0.0"
- },
- {
- "url": "Bit.Bswup.NewDemo.styles.css"
- },
- {
- "url": "Bit.Bswup.NewDemo.Client.bundle.scp.css"
- }
-];
-
-self.caseInsensitiveUrl = true;
-
-self.serverHandledUrls = [/\/api\//];
-self.serverRenderedUrls = [/\/privacy$/];
-
-self.noPrerenderQuery = 'no-prerender=true';
-
-self.isPassive = true;
-
-//self.enableDiagnostics = true;
-//self.enableFetchDiagnostics = true;
-
-self.importScripts('_content/Bit.Bswup/bit-bswup.sw.js');
diff --git a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/wwwroot/service-worker.published.js b/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/wwwroot/service-worker.published.js
deleted file mode 100644
index 7468555824..0000000000
--- a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/wwwroot/service-worker.published.js
+++ /dev/null
@@ -1,44 +0,0 @@
-// bit version: 10.5.0
-
-self.assetsInclude = [];
-self.assetsExclude = [
- /Bit\.Bswup\.NewDemo\.Client\.styles\.css$/
-];
-self.defaultUrl = '/';
-self.prohibitedUrls = [];
-self.assetsUrl = '/service-worker-assets.js';
-
-// more about SRI (Subresource Integrity) here: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
-// online tool to generate integrity hash: https://www.srihash.org/ or https://laysent.github.io/sri-hash-generator/
-// using only js to generate hash: https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest
-self.externalAssets = [
- {
- "url": "/"
- },
- {
- "url": "app.css"
- },
- {
- "url": "_framework/blazor.web.js?v=10.0.0"
- },
- {
- "url": "Bit.Bswup.NewDemo.styles.css"
- },
- {
- "url": "Bit.Bswup.NewDemo.Client.bundle.scp.css"
- }
-];
-
-self.caseInsensitiveUrl = true;
-
-self.serverHandledUrls = [/\/api\//];
-self.serverRenderedUrls = [/\/privacy$/];
-
-self.noPrerenderQuery = 'no-prerender=true';
-
-self.isPassive = true;
-
-//self.enableDiagnostics = true;
-//self.enableFetchDiagnostics = true;
-
-self.importScripts('_content/Bit.Bswup/bit-bswup.sw.js');
diff --git a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.csproj b/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.csproj
deleted file mode 100644
index e14bdfa8ce..0000000000
--- a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.csproj
+++ /dev/null
@@ -1,14 +0,0 @@
-
-
-
- net10.0
- enable
- enable
-
-
-
-
-
-
diff --git a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo/Components/App.razor b/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo/Components/App.razor
deleted file mode 100644
index 3110bb5054..0000000000
--- a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo/Components/App.razor
+++ /dev/null
@@ -1,38 +0,0 @@
-@code {
- [CascadingParameter] HttpContext HttpContext { get; set; } = default!;
-}
-
-@{
- var noPrerender = HttpContext.Request.Query["no-prerender"].Count > 0;
- var renderMode = new InteractiveWebAssemblyRenderMode(!noPrerender);
-}
-
-
-
-
-
- Error
-
-()
- .AddInteractiveServerRenderMode()
- .AddInteractiveWebAssemblyRenderMode()
- .AddAdditionalAssemblies(typeof(Bit.Bswup.NewDemo.Client._Imports).Assembly);
-
-app.Run();
diff --git a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo/appsettings.Development.json b/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo/appsettings.Development.json
deleted file mode 100644
index 0c208ae918..0000000000
--- a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo/appsettings.Development.json
+++ /dev/null
@@ -1,8 +0,0 @@
-{
- "Logging": {
- "LogLevel": {
- "Default": "Information",
- "Microsoft.AspNetCore": "Warning"
- }
- }
-}
diff --git a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo/appsettings.json b/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo/appsettings.json
deleted file mode 100644
index 10f68b8c8b..0000000000
--- a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo/appsettings.json
+++ /dev/null
@@ -1,9 +0,0 @@
-{
- "Logging": {
- "LogLevel": {
- "Default": "Information",
- "Microsoft.AspNetCore": "Warning"
- }
- },
- "AllowedHosts": "*"
-}
diff --git a/src/Bswup/Bit.Bswup.slnx b/src/Bswup/Bit.Bswup.slnx
index 2b41b652c7..85af14d2f4 100644
--- a/src/Bswup/Bit.Bswup.slnx
+++ b/src/Bswup/Bit.Bswup.slnx
@@ -6,14 +6,13 @@
-
+
-
-
+
-
net10.0;net9.0;net8.0
true
-
- BeforeBuildTasks;
- $(ResolveStaticWebAssetsInputsDependsOn)
-
+
+ es2019
@@ -21,41 +26,142 @@
+
-
-
-
+
+
+
+
+
-
-
+
-
+
-
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
-
\ No newline at end of file
+
diff --git a/src/Bswup/Bit.Bswup/BswupProgress.razor b/src/Bswup/Bit.Bswup/BswupProgress.razor
index 3d6344e5a2..35c432f0b0 100644
--- a/src/Bswup/Bit.Bswup/BswupProgress.razor
+++ b/src/Bswup/Bit.Bswup/BswupProgress.razor
@@ -1,7 +1,16 @@
@code {
[Parameter] public RenderFragment ChildContent { get; set; } = default!;
- [Parameter] public bool AutoReload { get; set; } = true;
+ // Whether a finished update is activated (and every open tab reloaded) automatically, or
+ // announced through the reload button for the user to accept. Defaults to false: an
+ // unprompted reload discards whatever in-page state the user has mid-session (a
+ // half-filled form has no other copy), which is a worse failure than running one version
+ // behind for a while - and it matches the prompt-then-reload pattern of the standard
+ // Blazor template and this package's own README sample. First installs are unaffected:
+ // they always complete the claim-and-start flow (no reload) regardless of this setting.
+ // CHANGED in v-10-6-0 - previous versions defaulted to true; set AutoReload="true"
+ // explicitly to keep the old behavior.
+ [Parameter] public bool AutoReload { get; set; } = false;
[Parameter] public bool ShowLogs { get; set; } = false;
[Parameter] public bool ShowAssets { get; set; } = false;
[Parameter] public string AppContainer { get; set; } = "#app";
@@ -10,24 +19,83 @@
[Parameter] public string? Handler { get; set; }
}
-
New version is available
-Downloading updates, please wait...
+ +
+
-
-
-
+
+
+ bit Bswup
+Preparing the app for offline use, please wait...
-
+
+
+ 0%
+ + -0 %
-Loading...
-
-
-
+
+
+
+ updateInterval="3600"
+ updateOnVisibility="true">
+
diff --git a/src/Bswup/Bit.Bswup.Demo/wwwroot/manifest.json b/src/Bswup/Bit.Bswup.Demo/wwwroot/manifest.json
index 4c9c96590a..91f455e630 100644
--- a/src/Bswup/Bit.Bswup.Demo/wwwroot/manifest.json
+++ b/src/Bswup/Bit.Bswup.Demo/wwwroot/manifest.json
@@ -1,6 +1,7 @@
-{
- "name": "Bit.Bswup.Demo",
- "short_name": "Bit.Bswup.Demo",
+{
+ "name": "bit Bswup",
+ "short_name": "Bswup",
+ "description": "Documentation and live showcase of bit Bswup - install progress, background updates, and offline support for Blazor WebAssembly apps.",
"start_url": "./",
"display": "standalone",
"background_color": "#ffffff",
diff --git a/src/Bswup/Bit.Bswup.Demo/wwwroot/service-worker.js b/src/Bswup/Bit.Bswup.Demo/wwwroot/service-worker.js
index 234b154b45..97ab20a5a6 100644
--- a/src/Bswup/Bit.Bswup.Demo/wwwroot/service-worker.js
+++ b/src/Bswup/Bit.Bswup.Demo/wwwroot/service-worker.js
@@ -1,14 +1,8 @@
-// bit version: 10.5.0
+// bit version: 10.5.0
-self.assetsExclude = [/\.scp\.css$/, /weather\.json$/];
+// Development service worker of the Bswup docs site. The site dogfoods Bswup even during
+// development so the full first-install / update experience is visible on plain F5.
+self.assetsExclude = [/\.scp\.css$/];
self.caseInsensitiveUrl = true;
-self.precachedAssetsInclude = [/favicon\.ico$/, /icon-512\.png$/, /bit-bw-64\.png$/];
-
-self.externalAssets = [
- {
- "url": "not-found/script.file.js"
- }
-];
-self.errorTolerance = 'lax';
self.importScripts('_content/Bit.Bswup/bit-bswup.sw.js');
diff --git a/src/Bswup/Bit.Bswup.Demo/wwwroot/service-worker.published.js b/src/Bswup/Bit.Bswup.Demo/wwwroot/service-worker.published.js
index 98df52a75d..fbb1eaf7c1 100644
--- a/src/Bswup/Bit.Bswup.Demo/wwwroot/service-worker.published.js
+++ b/src/Bswup/Bit.Bswup.Demo/wwwroot/service-worker.published.js
@@ -1,63 +1,13 @@
-// bit version: 10.5.0
+// bit version: 10.5.0
-self.assetsExclude = [/\.scp\.css$/, /weather\.json$/];
+self.assetsExclude = [/\.scp\.css$/];
self.caseInsensitiveUrl = true;
-self.precachedAssetsInclude = [/favicon\.ico$/, /icon-512\.png$/, /bit-bw-64\.png$/];
-//self.externalAssets = [
-// {
-// "url": "not-found/script.file.js"
-// }
-//];
-//self.errorTolerance = 'lax';
+//// Resiliency knobs (see the Bswup README for details):
+//self.errorTolerance = 'strict'; // abort the install if any asset fails ('lax' = best-effort lazy-fill, the default)
+//self.maxRetries = 2; // extra download attempts on transient failures (408/429/5xx, dropped connections)
+//self.retryDelay = 300; // base backoff in ms between those retries (exponential, with jitter)
+//self.enableIntegrityCheck = true; // attach SRI hashes so tampered assets are rejected (requires byte-identical serving)
+//self.cacheVersion = '2026.07.28-abc1234'; // pin/bump the cache bucket independently of the asset manifest
self.importScripts('_content/Bit.Bswup/bit-bswup.sw.js');
-
-//// Caution! Be sure you understand the caveats before publishing an application with
-//// offline support. See https://aka.ms/blazor-offline-considerations
-
-//self.importScripts('./service-worker-assets.js');
-//self.addEventListener('install', event => event.waitUntil(onInstall(event)));
-//self.addEventListener('activate', event => event.waitUntil(onActivate(event)));
-//self.addEventListener('fetch', event => event.respondWith(onFetch(event)));
-
-//const cacheNamePrefix = 'offline-cache-';
-//const cacheName = `${cacheNamePrefix}${self.assetsManifest.version}`;
-//const offlineAssetsInclude = [ /\.dll$/, /\.pdb$/, /\.wasm/, /\.html/, /\.js$/, /\.json$/, /\.css$/, /\.woff$/, /\.png$/, /\.jpe?g$/, /\.gif$/, /\.ico$/, /\.blat$/, /\.dat$/ ];
-//const offlineAssetsExclude = [ /^service-worker\.js$/ ];
-
-//async function onInstall(event) {
-// console.info('Service worker: Install');
-
-// // Fetch and cache all matching items from the assets manifest
-// const assetsRequests = self.assetsManifest.assets
-// .filter(asset => offlineAssetsInclude.some(pattern => pattern.test(asset.url)))
-// .filter(asset => !offlineAssetsExclude.some(pattern => pattern.test(asset.url)))
-// .map(asset => new Request(asset.url, { integrity: asset.hash }));
-// await caches.open(cacheName).then(cache => cache.addAll(assetsRequests));
-//}
-
-//async function onActivate(event) {
-// console.info('Service worker: Activate');
-
-// // Delete unused caches
-// const cacheKeys = await caches.keys();
-// await Promise.all(cacheKeys
-// .filter(key => key.startsWith(cacheNamePrefix) && key !== cacheName)
-// .map(key => caches.delete(key)));
-//}
-
-//async function onFetch(event) {
-// let cachedResponse = null;
-// if (event.request.method === 'GET') {
-// // For all navigation requests, try to serve index.html from cache
-// // If you need some URLs to be server-rendered, edit the following check to exclude those URLs
-// const shouldServeIndexHtml = event.request.mode === 'navigate';
-
-// const request = shouldServeIndexHtml ? 'index.html' : event.request;
-// const cache = await caches.open(cacheName);
-// cachedResponse = await cache.match(request);
-// }
-
-// return cachedResponse || fetch(event.request);
-//}
diff --git a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/Layout/DemoBswupProgressBar.razor b/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/Layout/DemoBswupProgressBar.razor
deleted file mode 100644
index 19a3f2febc..0000000000
--- a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/Layout/DemoBswupProgressBar.razor
+++ /dev/null
@@ -1,27 +0,0 @@
-
-
-@*
-
-
-
*@
-
-
-
- Loading...
-
-
-
-
-
-
-
-
-
-
diff --git a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/Layout/MainLayout.razor.css b/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/Layout/MainLayout.razor.css
deleted file mode 100644
index df8c10ff29..0000000000
--- a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/Layout/MainLayout.razor.css
+++ /dev/null
@@ -1,18 +0,0 @@
-#blazor-error-ui {
- background: lightyellow;
- bottom: 0;
- box-shadow: 0 -1px 2px rgba(0, 0, 0, 0.2);
- display: none;
- left: 0;
- padding: 0.6rem 1.25rem 0.7rem 1.25rem;
- position: fixed;
- width: 100%;
- z-index: 1000;
-}
-
- #blazor-error-ui .dismiss {
- cursor: pointer;
- position: absolute;
- right: 0.75rem;
- top: 0.5rem;
- }
diff --git a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/Program.cs b/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/Program.cs
deleted file mode 100644
index 519269f21b..0000000000
--- a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/Program.cs
+++ /dev/null
@@ -1,5 +0,0 @@
-using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
-
-var builder = WebAssemblyHostBuilder.CreateDefault(args);
-
-await builder.Build().RunAsync();
diff --git a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/Routes.razor b/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/Routes.razor
deleted file mode 100644
index d0df781615..0000000000
--- a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo.Client/Routes.razor
+++ /dev/null
@@ -1,6 +0,0 @@
-111
-Error.
-An error occurred while processing your request.
- -@if (ShowRequestId) -{ -
- Request ID: @RequestId
-
Development Mode
-- Swapping to Development environment will display more detailed information about the error that occurred. -
-- The Development environment shouldn't be enabled for deployed applications. - It can result in displaying sensitive information from exceptions to end users. - For local debugging, enable the Development environment by setting the ASPNETCORE_ENVIRONMENT environment variable to Development - and restarting the app. -
- -@code{ - [CascadingParameter] - private HttpContext? HttpContext { get; set; } - - private string? RequestId { get; set; } - private bool ShowRequestId => !string.IsNullOrEmpty(RequestId); - - protected override void OnInitialized() => - RequestId = Activity.Current?.Id ?? HttpContext?.TraceIdentifier; -} diff --git a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo/Program.cs b/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo/Program.cs deleted file mode 100644 index 668876cc8a..0000000000 --- a/src/Bswup/Bit.Bswup.NewDemo/Bit.Bswup.NewDemo/Program.cs +++ /dev/null @@ -1,34 +0,0 @@ -using Bit.Bswup.NewDemo.Components; - -var builder = WebApplication.CreateBuilder(args); - -// Add services to the container. -builder.Services.AddRazorComponents() - .AddInteractiveServerComponents() - .AddInteractiveWebAssemblyComponents(); - -var app = builder.Build(); - -// Configure the HTTP request pipeline. -if (app.Environment.IsDevelopment()) -{ - app.UseWebAssemblyDebugging(); -} -else -{ - app.UseExceptionHandler("/Error", createScopeForErrors: true); - // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts. - app.UseHsts(); -} - -app.UseHttpsRedirection(); - -app.MapStaticAssets(); -app.UseAntiforgery(); - -app.MapRazorComponents
- @if (ChildContent is not null)
+@* Configuration is published as data-* attributes and read by bit-bswup.progress.js when it
+ loads (it self-initializes from these attributes). This deliberately avoids emitting an
+ inline
+
+
+
+