Definition

install event (service worker)

Short definition

The install event fires on the ServiceWorkerGlobalScope the first time a browser registers a new or updated service worker script. Handlers typically call event.waitUntil(caches.open(...).then(cache => cache.addAll([...]))) to pre-cache the app shell before the worker is allowed to move to the "installed" state.

Reviewed July 25, 2026

A minimal handler looks like: self.addEventListener("install", (event) => { event.waitUntil(caches.open("shell-v1").then((cache) => cache.addAll(["/", "/app.css", "/app.js"]))); });. If any addAll request fails, the whole install step fails and the new worker is discarded.

Install runs for every updated script, not just the very first registration — the browser detects an update by byte-comparing the new script against the previously stored one, and re-runs install whenever they differ.

A newly installed worker does not take over existing open pages immediately; it enters the "waiting" state until all clients controlled by the old worker are closed, unless the code calls self.skipWaiting().

See the MDN Service Worker API lifecycle documentation for the full event sequence: https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers.

Related terms

activate event (service worker)

The activate event fires after a service worker moves from "installed" to "activating", typically once the old worker's clients have all closed or skipWaiting() was called. Handlers commonly use it to clean up outdated Cache Storage entries left behind by earlier versions of the app shell.

skipWaiting()

self.skipWaiting() is called inside a service worker's install (or activate) handler to skip the normal waiting state and activate immediately, even while older pages controlled by a previous worker are still open. It is usually paired with clients.claim() so the new worker also starts controlling those pages right away.

Precaching

Precaching means fetching and storing a known list of build-time assets (HTML shell, CSS, JS bundles, key icons) in Cache Storage inside the install event handler, so they are guaranteed to be available offline from the very first load rather than being cached only after a user happens to request them.

fetch event (service worker)

The fetch event fires in the service worker for every navigation, script, image or XHR request originating from a page it controls. Calling event.respondWith(promise) lets the worker substitute its own Response, most commonly by checking the Cache Storage API first and falling back to fetch() from the network.

waiting state (service worker)

A service worker enters the waiting state after install succeeds but before it can activate, because the browser only replaces an active worker once every page it currently controls has been closed or navigated away from. It stays here indefinitely until those pages close or the code forces the transition with skipWaiting().

clients.claim()

self.clients.claim() is called inside the activate event of a service worker to make it start controlling every open page on the origin right away, rather than the default behaviour where a page keeps being controlled by whatever worker was active when it first loaded until the next navigation.