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:

BitBswup.forceRefresh();                          // Bswup + Blazor caches (default)
BitBswup.forceRefresh(() => true);                // every cache on the origin
BitBswup.forceRefresh('bit-bswup');               // only Bswup's own caches
BitBswup.forceRefresh(/^(bit-bswup|my-app-data)/) // a specific set

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:

1. Set updateInterval (and/or updateOnVisibility) on the script tag for built-in polling. Simplest, no extra code - this site uses both.
2. Call BitBswup.checkForUpdate() yourself, from a timer or after a user action:

// an ordinary failed check (offline, server hiccup) does NOT reject - it is reported through
// the UPDATE_CHECK_FAILED message below. This catch is only for unexpected errors, such as a
// call made before the registration is ready.
const checkNow = () => BitBswup.checkForUpdate()
    .catch(err => console.warn('unexpected update check error:', err));

// check every hour from your own code (equivalent to updateInterval="3600")
setInterval(checkNow, 60 * 60 * 1000);

// or check whenever the user clicks a button, and react to the result
document.getElementById('check-updates').onclick = checkNow;

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:

window.bitBswupHandler = (message, data) => {
    switch (message) {
        case 'UPDATE_NOT_FOUND': /* already up to date - stop the spinner */ break;
        case 'UPDATE_CHECK_FAILED': /* transient failure - keep running, optionally notify */ break;
        // updateFound / stateChanged / updateReady / downloadFinished drive the update UI
    }
};