Websites · Glossary
What is a service worker?
A service worker is a JavaScript file that a website registers with the browser and that runs separately from the page. It sits between the site and the network, so it can answer requests from a cache, show an offline page when the connection drops, and receive events such as push messages. It works only on HTTPS.
A service worker is the part of an installable website that decides what happens when the network is slow or gone. It never touches the page directly; it intercepts requests and chooses whether to answer from the network or from a cache.
Nuwan Madhusanka · Co-founder
4 min read · Published
| Stage | What happens | What the site usually does here |
|---|---|---|
| Register | The page calls navigator.serviceWorker.register() with the script's URL | Register once, after the page has loaded, so it does not slow the first visit |
| Install | The browser downloads the script and fires the install event | Open a cache and store the files the offline experience needs |
| Waiting | A new version waits while an old one still controls open tabs | Leave it, or call skipWaiting() when the change is safe |
| Activate | The new worker takes over and fires the activate event | Delete caches that belonged to older versions |
| Fetch | Every request from pages in scope passes through the worker | Answer from the cache, from the network, or fall back to the offline page |
What a service worker is
A service worker is a script the browser keeps apart from the page. It has no access to the page's elements; instead it listens for events. The most important is fetch, which fires for every request a page in its scope makes, whether for a stylesheet, an image or a page. The worker can let the request go to the network, answer it from a cache it manages, or build a response itself. Because it can rewrite responses, browsers only allow service workers on HTTPS, with localhost allowed for development. A worker controls the pages under the folder it is served from, which is called its scope, so a worker at the site root controls the whole site.
How it works in practice
The page registers the worker, usually with one line after load. The browser downloads the script and fires install, where the worker typically stores a small set of files in a named cache: an offline page, a logo, a stylesheet. When the worker activates, it clears caches from older versions. From then on, every request passes through its fetch handler. Common strategies are network first (try the network, fall back to the cache), cache first (answer from the cache, which is fast but can be stale) and stale while revalidate (answer from the cache and refresh it in the background). A new version of the script installs alongside the old one and waits until no tab uses the old version, which is why updates can seem slow to appear.
When it matters for a small business
A service worker is one of the requirements for a site to behave like an installed app. It matters when customers open the site on poor mobile signal, such as at a market stall, a beach kiosk or a sports ground, because a cached offline page with the phone number is better than a browser error. It matters for repeat visitors, since cached styles and images load faster on the second visit. It does not make a site rank higher on its own, and a site that is not installable gains little from one, so it is worth adding only when you want the installed experience.
Common mistakes
Caching pages that change, such as prices, stock, bookings or a cart, so visitors see yesterday's numbers. Caching everything with cache first and never expiring it, which leaves a site stuck on an old design after an update. Forgetting that a waiting worker does not take over until tabs close, then assuming the deploy failed. Registering the worker from a subfolder, so it controls only part of the site. Treating it as a security feature: it runs in the visitor's browser and can be removed by them. And caching responses that carry personal data, which then sit in the browser's storage on a shared device.
Where it shows up in OneCraft
Websites built with OneCraft are written as code, and a site becomes installable when you ask for it: the pwa capability guide adds a manifest, SVG icons, an offline page, a service worker and an install offer. The worker it writes caches only the offline page, never data from the site's own database, so prices, bookings and orders always come fresh from the network. The pwa guide is for websites only; a phone app is a separate Expo project with its own build.
Questions people ask
Do I need a service worker to make my site installable?
Most browsers expect a web app manifest and a site served over HTTPS before they offer to install it, and an offline experience through a service worker is part of what makes the installed site useful. Requirements differ between browsers and change over time, so check the browser documentation before relying on an install prompt.
Can a service worker slow down my website?
It can if it is written badly, for example if the fetch handler waits on slow cache lookups before every request or precaches large files during the first visit. A small worker that caches a few files after the page has loaded has no noticeable cost and makes repeat visits faster.
How do I remove a service worker from my site?
Deploy a new worker that unregisters itself and deletes its caches, or serve a script that does nothing at the same address. Deleting the file alone is not enough, because browsers keep the installed worker until a new version replaces it. Visitors can also remove it in their browser's site settings.
Does a service worker work on iPhone?
Yes. Safari on iPhone supports service workers for caching and offline pages. Some related features, such as web push notifications for a site, only work after the visitor adds the site to the home screen. Test the offline page on a real iPhone before telling customers it works offline.
Is a service worker the same as a web worker?
No. A web worker runs heavy code in the background for one page and stops when that page closes. A service worker sits between all pages in its scope and the network, survives page closes, and handles events such as fetch and push. They share the idea of running off the main thread.
Make one with websites
The button opens the generator with this use case already described. Change the wording to match your own.
Create a website with OneCraftRelated questions
- What is a web app manifest?What is a web app manifest? The JSON file that gives an installable website its name, icons, colours, start address and display mode, member by member.
- What is a PWA?What is a PWA? A website that can be installed to a phone home screen and opened full screen like an app, with an icon and an offline page. How it works.
- What is a hydration error in React?What is a hydration error? When server rendered HTML and React's first render in the browser disagree. Common causes, how to read the message and how to fix it.
- What is a managed SSL certificate?What is a managed SSL certificate? One your host issues, validates and renews for you, compared with buying and installing a certificate yourself.
Written and checked by the OneCraft team. Last checked .