Service worker

Sudden uses a service worker to see and cache HLS playlists and segments so it can offload traffic from your CDN. This page explains how to host the required loader file and how to integrate Sudden with or without an existing service worker setup.

Basic setup

Use this setup if you are not already using a service worker on your site. In this mode, Sudden registers its own worker using the loader file you provide.

Add the loader file on your site origin

Create a small script file on your site origin (the same domain where your player runs), for example at https://your-domain.com/sudden.service-worker.js:

https://your-domain.com/sudden.service-worker.js


self.importScripts("https://js.sudden.network/service-worker.js");

This loader imports Sudden’s service worker from Sudden’s domain.

Tell Sudden where the loader lives

In your Sudden config, set serviceWorkerPath to the path of the loader file:


await sudden.init({
  clientId: "YOUR_CLIENT_ID",
  serviceWorkerPath: "/sudden.service-worker.js",
});

or with React:


import React from "react";
 
import { SuddenProvider } from "@sudden-network/sudden/react";
 
export const App = () => (
  <SuddenProvider
    config={{
      clientId: "YOUR_CLIENT_ID",
      serviceWorkerPath: "/sudden.service-worker.js",
    }}
  >
    {/* your app */}
  </SuddenProvider>
);

Sudden will register the loader as a service worker with a scope of /, so it can see relevant HLS requests on your site.

Load your player after initialization

Await sudden.init before loading your HLS playlist so the service worker can intercept the very first request.


await sudden.init({
  clientId: "YOUR_CLIENT_ID",
  serviceWorkerPath: "/sudden.service-worker.js",
});
// Now configure your HLS player and set the playlist URL

Integrating with an existing service worker

If you already have a service worker stack (for offline support, push notifications, etc.), you may not want Sudden to register another worker for the same scope. In that case, you are responsible for importing Sudden’s worker code into your existing service worker.

Import Sudden in your existing service worker

In your current service worker file, add:


self.importScripts("https://js.sudden.network/service-worker.js");

This lets Sudden run inside your existing service worker context. Place this import near the top of the file, before your own service worker handlers.

Do not set `serviceWorkerPath` in Sudden config

When you call sudden.init or configure SuddenProvider, omit the serviceWorkerPath field:


await sudden.init({
  clientId: "YOUR_CLIENT_ID",
  // serviceWorkerPath omitted on purpose
});

Sudden will then assume that you manage service worker registration yourself and will not try to register another one.

Ensure scope covers your video pages

Make sure your existing service worker’s scope includes the pages where you use Sudden and your HLS players. Sudden can only help where its code is running inside an active worker.

Avoid registering multiple service workers for the same scope. Pick one registration strategy (Sudden-managed or your own) and stick to it, while ensuring Sudden’s worker code is imported once via importScripts.

Choosing a path

If Sudden registers the worker for you, we recommend a simple path like "/sudden.service-worker.js".
If you already have a worker, keep using your existing path; only the importScripts line needs to be added.

In all cases, the path and scope you choose should match how your site is structured and which pages you want Sudden to help on.