use-service-worker


Package	`@vizejs/composable/use-service-worker`
Own the source	`vize lib pull composable:use-service-worker`
Runtime exports	`useServiceWorker`
Gzip budget	2304 B

Usage

import { useServiceWorker } from "@vizejs/composable/use-service-worker";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useServiceWorker`	networking	experimental	deterministic-fallback	caller-managed	reactive-scope	web, desktop	`window`	`tryOnScopeDispose`

API

`useServiceWorker`

Register a service worker and follow its update lifecycle. Tracks updatefound and each worker's statechange so state mirrors the installing, waiting and active workers. updateAvailable turns true once an installed worker waits while another one controls the page; skipWaiting() then posts the configured message to it, and onControllerChange runs once it takes control. Listeners are removed when the owning reactive scope stops; outside a scope they live as long as the registration. Server rendering: nothing is registered, supported is false and every state is null.

function useServiceWorker( scriptUrl: MaybeRefOrGetter<string | URL>, options: UseServiceWorkerOptions = {}, ): ServiceWorkerControls

const sw = useServiceWorker("/sw.js", {
  onControllerChange: () => window.location.reload(),
});
const applyUpdate = () => sw.skipWaiting();

Types

`ServiceWorkerLike`

Minimal ServiceWorker consumed by useServiceWorker.

Member	Type	Description
`state`	`ServiceWorkerStateName`	Current lifecycle state; changes fire `statechange`.
`postMessage`	`(message: unknown) => void`	Post a message to the worker.

`ServiceWorkerRegistrationLike`

Minimal ServiceWorkerRegistration consumed by useServiceWorker.

Member	Type	Description
`installing`	`ServiceWorkerLike \| null`	Worker being installed, if any; a new one fires `updatefound`.
`waiting`	`ServiceWorkerLike \| null`	Installed worker waiting to take over, if any.
`active`	`ServiceWorkerLike \| null`	Active worker, if any.
`scope`	`string`	Registration scope URL.
`update`	`() => Promise<unknown>`	Check the server for an updated script.
`unregister`	`() => Promise<boolean>`	Unregister; resolves whether the registration was removed.

`ServiceWorkerRegisterOptions`

Options forwarded to ServiceWorkerContainer.register.

Member	Type	Description
`scope`?	`string`	Registration scope.
`type`?	`"classic" \| "module"`	Script type.
`updateViaCache`?	`"imports" \| "all" \| "none"`	HTTP cache policy for update checks.

`ServiceWorkerContainerLike`

Minimal ServiceWorkerContainer (navigator.serviceWorker).

Member	Type	Description
`controller`	`ServiceWorkerLike \| null`	Worker controlling this page; changes fire `controllerchange`.
`register`	`(scriptUrl: string \| URL, options?: ServiceWorkerRegisterOptions) => Promise<ServiceWorkerRegistrationLike>`	Register a service worker script.

`ServiceWorkerStates`

States of the registration's workers (null when absent).

Member	Type	Description
`installing`	`ServiceWorkerStateName \| null`	State of the installing worker.
`waiting`	`ServiceWorkerStateName \| null`	State of the waiting worker.
`active`	`ServiceWorkerStateName \| null`	State of the active worker.

`UseServiceWorkerOptions`

Options for useServiceWorker.

Member	Type	Description
`container`?	`MaybeRefOrGetter<ServiceWorkerContainerLike \| null \| undefined>`	Service worker container for alternate runtimes and tests.
`scope`?	`string`	Registration scope.
`type`?	`"classic" \| "module"`	Script type.
`updateViaCache`?	`"imports" \| "all" \| "none"`	HTTP cache policy for update checks.
`immediate`?	`boolean`	Register as soon as the composable is created (browser only).
`skipWaitingMessage`?	`unknown`	Message posted to the waiting worker by `skipWaiting()`.
`onControllerChange`?	`(controller: ServiceWorkerLike \| null) => void`	Called on `controllerchange` (for example to reload the page after a new worker took control).

`ServiceWorkerControls`

Reactive state and actions returned by useServiceWorker.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether the Service Worker API is available.
`registration`	`Readonly<ShallowRef<ServiceWorkerRegistrationLike \| null>>`	Current registration, or `null` before registering.
`state`	`Readonly<Ref<ServiceWorkerStates>>`	States of the installing, waiting and active workers.
`updateAvailable`	`ComputedRef<boolean>`	Whether a waiting worker is ready to replace the controlling one.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent failure, cleared by the next successful action.
`register`	`() => Promise<ServiceWorkerRegistrationLike \| null>`	Register (or re-register) the script.
`update`	`() => Promise<boolean>`	Check the server for an updated script.
`skipWaiting`	`() => boolean`	Post the skip-waiting message to the waiting worker.
`unregister`	`() => Promise<boolean>`	Unregister the service worker.