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.

<script src="_content/Bit.Bswup/bit-bswup.js"
        scope="/"
        log="verbose"
        sw="service-worker.js"
        handler="bitBswupHandler"
        blazorScript="_framework/blazor.webassembly.js"
        updateInterval="3600"
        updateOnVisibility="true"
        stallTimeout="60"
        persistStorage="false"
        options="bitBswup"></script>

Quick reference

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.

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.

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.

<script>
    window.bitBswup = { sw: 'my-sw.js', updateInterval: 3600 };
</script>
<!-- ...later, possibly injected dynamically: -->
<script src="_content/Bit.Bswup/bit-bswup.js"></script>