Service workers

Service workers act as proxy servers that handle network requests inside your app. This makes it possible to make your app work offline and speed up navigation by precaching built assets.

Setup

If you have a src/service-worker.js file (or src/service-worker/index.js), SvelteKit will bundle and automatically register it.

Service workers are bundled for production but not during development.

Automatic registration

The default registration looks like this:

if ('serviceWorker' in navigator) {
	addEventListener('load', function () {
		navigator.serviceWorker.register('./path/to/service-worker.js');
	});
}

Custom registration

You can disable automatic registration and register manually:

import { dev } from '$app/environment';

navigator.serviceWorker.register('/service-worker.js', {
	type: dev ? 'module' : 'classic'
});

During development, you must pass type: 'module' because only browsers that support modules in service workers can use them at dev time.

Inside the service worker

The $service-worker module provides access to:

string[]

Paths to all built app files

string[]

Paths to all files in the static directory

string[]

Paths to all prerendered pages

string

A unique app version string for creating cache names

string

The deployment’s base path

Complete example

This example caches the built app and static files eagerly, then caches other requests as they happen:

src/service-worker.js

// Type safety references
/// <reference no-default-lib="true"/>
/// <reference lib="esnext" />
/// <reference lib="webworker" />
/// <reference types="@sveltejs/kit" />
/// <reference types="../.svelte-kit/ambient.d.ts" />

import { build, files, version } from '$service-worker';

const self = /** @type {ServiceWorkerGlobalScope} */ (/** @type {unknown} */ (globalThis.self));

// Create a unique cache name for this deployment
const CACHE = `cache-${version}`;

const ASSETS = [
	...build, // the app itself
	...files  // everything in `static`
];

self.addEventListener('install', (event) => {
	// Create a new cache and add all files to it
	async function addFilesToCache() {
		const cache = await caches.open(CACHE);
		await cache.addAll(ASSETS);
	}

	event.waitUntil(addFilesToCache());
});

self.addEventListener('activate', (event) => {
	// Remove previous cached data from disk
	async function deleteOldCaches() {
		for (const key of await caches.keys()) {
			if (key !== CACHE) await caches.delete(key);
		}
	}

	event.waitUntil(deleteOldCaches());
});

self.addEventListener('fetch', (event) => {
	// ignore POST requests etc
	if (event.request.method !== 'GET') return;

	async function respond() {
		const url = new URL(event.request.url);
		const cache = await caches.open(CACHE);

		// `build`/`files` can always be served from the cache
		if (ASSETS.includes(url.pathname)) {
			const response = await cache.match(url.pathname);

			if (response) {
				return response;
			}
		}

		// for everything else, try the network first, but
		// fall back to the cache if we're offline
		try {
			const response = await fetch(event.request);

			// if we're offline, fetch can return a value that is not a Response
			// instead of throwing - and we can't pass this non-Response to respondWith
			if (!(response instanceof Response)) {
				throw new Error('invalid response from fetch');
			}

			if (response.status === 200) {
				cache.put(event.request, response.clone());
			}

			return response;
		} catch (err) {
			const response = await cache.match(event.request);

			if (response) {
				return response;
			}

			// if there's no cache, then just error out
			// as there is nothing we can do to respond to this request
			throw err;
		}
	}

	event.respondWith(respond());
});

Install event

Opens a cache and adds all static assets to it

Activate event

Removes old caches from previous deployments

Fetch event

Serves cached assets immediately, network resources with cache fallback

Caching strategies

Cache-first

Check the cache first, fall back to network. Best for static assets.

const response = await cache.match(request) || await fetch(request);

Network-first

Try network first, fall back to cache if offline. Best for dynamic content.

try {
  const response = await fetch(request);
  cache.put(request, response.clone());
  return response;
} catch (err) {
  return await cache.match(request);
}

Stale-while-revalidate

Return cached response immediately while fetching fresh data in background.

const cached = await cache.match(request);
const fresh = fetch(request).then(r => {
  cache.put(request, r.clone());
  return r;
});
return cached || fresh;

Be careful when caching! In some cases, stale data might be worse than no data. Browsers will also empty caches if they get too full.

Development considerations

During development:

Service workers are not bundled
build and prerendered are empty arrays
Only browsers that support ES modules in service workers will work

Testing

Build your app

npm run build

Preview the build

npm run preview

Test offline

Open DevTools → Network tab → Enable “Offline” mode

Verify caching

Open DevTools → Application tab → Service Workers / Cache Storage

Alternative solutions

SvelteKit’s service worker implementation is simple and effective, but you might prefer:

Workbox

Google’s comprehensive PWA library with advanced caching strategies

Vite PWA Plugin

Workbox integration for Vite-based projects including SvelteKit

Learn more

MDN Web Docs: Using Service Workers

Getting Started

Core Concepts

Build and Deploy

Advanced

Setup

Automatic registration

Custom registration

Inside the service worker

Complete example

Caching strategies

Development considerations

Testing

Alternative solutions

Workbox

Vite PWA Plugin

Learn more

​Setup

​Automatic registration

​Custom registration

​Inside the service worker

​Complete example

​Caching strategies

​Development considerations

​Testing

​Alternative solutions

Workbox

Vite PWA Plugin

Learn more

Setup

Automatic registration

Custom registration

Inside the service worker

Complete example

Caching strategies

Development considerations

Testing

Alternative solutions