Service workers

Edit this page on GitHub

Service workers act as proxy servers that handle network requests inside your app. This makes it possible to make your app work offline, but even if you don't need offline support (or can't realistically implement it because of the type of app you're building), it's often worth using service workers to speed up navigation by precaching your built JS and CSS.

In SvelteKit, if you have a src/service-worker.js file (or src/service-worker.ts, src/service-worker/index.js, etc) it will be bundled and automatically registered. You can change the location of your service worker if you need to.

You can disable automatic registration if you need to register the service worker with your own logic or use another solution. The default registration looks something like this:

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

Inside the service workerpermalink

Inside the service worker you have access to the $service-worker module, which provides you with the paths to all static assets, build files and prerendered pages. You're also provided with an app version string, which you can use for creating a unique cache name, and the deployment's base path. If your Vite config specifies define (used for global variable replacements), this will be applied to service workers as well as your server/client builds.

The following example caches the built app and any files in static eagerly, and caches all other requests as they happen. This would make each page work offline once visited.

ts
/// <reference types="@sveltejs/kit" />
import { build, files, version } from '$service-worker';
 
// 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);
Property 'waitUntil' does not exist on type 'Event'.2339Property 'waitUntil' does not exist on type 'Event'.    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);
Property 'waitUntil' does not exist on type 'Event'.2339Property 'waitUntil' does not exist on type 'Event'.    }
  }
 
  event.waitUntil(deleteOldCaches());
});
Property 'request' does not exist on type 'Event'.2339Property 'request' does not exist on type 'Event'. 
self.addEventListener('fetch', (event) => {
  // ignore POST requests etc
Property 'request' does not exist on type 'Event'.2339Property 'request' does not exist on type 'Event'.  if (event.request.method !== 'GET') return;
 
  async function respond() {
    const url = new URL(event.request.url);
    const cache = await caches.open(CACHE);
Property 'request' does not exist on type 'Event'.2339Property 'request' does not exist on type 'Event'. 
    // `build`/`files` can always be served from the cache
    if (ASSETS.includes(url.pathname)) {
      return cache.match(event.request);
    }
 
Property 'request' does not exist on type 'Event'.2339Property 'request' does not exist on type 'Event'.    // for everything else, try the network first, but
    // fall back to the cache if we're offline
    try {
Property 'request' does not exist on type 'Event'.2339Property 'request' does not exist on type 'Event'.      const response = await fetch(event.request);
 
      if (response.status === 200) {
        cache.put(event.request, response.clone());
      }
Property 'request' does not exist on type 'Event'.2339Property 'request' does not exist on type 'Event'. 
      return response;
    } catch {
      return cache.match(event.request);
Property 'respondWith' does not exist on type 'Event'.2339Property 'respondWith' does not exist on type 'Event'.    }
  }
 
  event.respondWith(respond());
});

Be careful when caching! In some cases, stale data might be worse than data that's unavailable while offline. Since browsers will empty caches if they get too full, you should also be careful about caching large assets like video files.

During developmentpermalink

The service worker is bundled for production, but not during development. For that reason, only browsers that support modules in service workers will be able to use them at dev time. If you are manually registering your service worker, you will need to pass the { type: 'module' } option in development:

ts
import { dev } from '$app/environment';
 
navigator.serviceWorker.register('/service-worker.js', {
  type: dev ? 'module' : 'classic'
});

build and prerendered are empty arrays during development

Type safetypermalink

Setting up proper types for service workers requires some manual setup. Inside your service-worker.js, add the following to the top of your file:

ts
/// <reference types="@sveltejs/kit" />
/// <reference no-default-lib="true"/>
/// <reference lib="esnext" />
/// <reference lib="webworker" />
 
const sw = /** @type {ServiceWorkerGlobalScope} */ (/** @type {unknown} */ (self));

ts
/// <reference types="@sveltejs/kit" />
/// <reference no-default-lib="true"/>
/// <reference lib="esnext" />
/// <reference lib="webworker" />
 
const sw = self as unknown as ServiceWorkerGlobalScope;

This disables access to DOM typings like HTMLElement which are not available inside a service worker and instantiates the correct globals. The reassignment of self to sw allows you to type cast it in the process (there are a couple of ways to do this, but the easiest that requires no additional files). Use sw instead of self in the rest of the file. The reference to the SvelteKit types ensures that the $service-worker import has proper type definitions.

Service workers

Inside the service workerpermalink

During developmentpermalink

Type safetypermalink

Other solutionspermalink