use-service-worker

Register a service worker and follow its update lifecycle.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

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

Try it

Enable offline mode

Register a service worker on request and offer a reload when an update is waiting.

Open the interactive example

What to observe: Enable offline mode registers /sw.js in an app that serves it; Reload to update appears when a new version is waiting.

Serve the worker script from your app's public directory. skipWaiting sends the configured message to the waiting worker. Every example renders a neutral message until it mounts, so server and client markup match, and then explains what to do when the browser lacks the API.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { useMounted } from "@vizejs/composable/use-mounted";
import { useServiceWorker } from "@vizejs/composable/use-service-worker";

const mounted = useMounted();
// Serve `/sw.js` from your app's public directory.
const { supported, state, updateAvailable, register, skipWaiting } = useServiceWorker("/sw.js", {
  immediate: false,
});
</script>

<template>
  <div class="composable-example">
    <p>Install offline support on request and offer a reload when an update is waiting.</p>
    <div class="example-actions">
      <button type="button" :disabled="!mounted || !supported" @click="() => register()">
        Enable offline mode
      </button>
      <button type="button" :disabled="!updateAvailable" @click="() => skipWaiting()">
        Reload to update
      </button>
    </div>
    <output aria-live="polite">{{
      !mounted
        ? "Checking browser support…"
        : supported
          ? `Service worker: ${state}`
          : "Service workers are not available in this browser."
    }}</output>
  </div>
</template>

Runtime contract

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.

ServiceWorkerRegistrationLike

Minimal ServiceWorkerRegistration consumed by useServiceWorker.

ServiceWorkerRegisterOptions

Options forwarded to ServiceWorkerContainer.register.

ServiceWorkerContainerLike

Minimal ServiceWorkerContainer (navigator.serviceWorker).

ServiceWorkerStates

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

UseServiceWorkerOptions

Options for useServiceWorker.

ServiceWorkerControls

Reactive state and actions returned by useServiceWorker.