docs-serwist-core-serwist.md
9.0.0
A class that helps bootstrap the service worker.
precacheEntries — A list of URLs that should be cached.
precacheOptions — Options to customize how Serwist precaches the URLs in the precache list.
cacheName — Cache name to store and retrieve requests. Defaults to Serwist’s default cache names.plugins — Plugins to use when precaching as well as responding to fetch events for precached assets.fetchOptions — Options passed to non-navigation fetch() calls made by this strategy.matchOptions — The CacheQueryOptions passed to any cache.match() or cache.put() call made by this strategy.fallbackToNetwork — Whether to attempt to get the response from the network if there’s a precache miss.directoryIndex — Tells Serwist to check the precache for an entry whose URL is the request URL appended with the specified value. Only applies if the request URL ends with ”/“.ignoreURLParametersMatching — An array of RegExp objects matching search params that should be removed when looking for a precache match.cleanURLs — Tells Serwist to check the precache for an entry whose URL is the request URL appended with “.html”.urlManipulation — A function that should take a URL and return an array of alternative URLs that should be checked for precache matches.cleanupOutdatedCaches — Whether outdated caches should be removed.concurrency — The number of precache requests that should be made concurrently.navigateFallback — An URL that should point to a HTML file with which navigation requests for URLs that aren’t precached will be fulfilled.navigateFallbackAllowlist — URLs that should be allowed to use the navigateFallback handler.navigateFallbackDenylist — URLs that should not be allowed to use the navigateFallback handler. This takes precedence over navigateFallbackAllowlist.skipWaiting — Forces the waiting service worker to become the active one.
importScripts — Imports external scripts. They are executed in the order they are passed.
navigationPreload — Enables navigation preloading if it is supported.
cacheId — Modifies the prefix of the default cache names used by Serwist packages.
clientsClaim — Claims any currently available clients once the service worker becomes active. This is normally used in conjunction with skipWaiting().
runtimeCaching — A list of caching strategies.
offlineAnalyticsConfig — Your configuration for initializeGoogleAnalytics. This plugin is only initialized when this option is not undefined or false.
disableDevLogs — Disables Serwist’s logging in development mode.
fallbacks — Precaches routes so that they can be used as a fallback when a Strategy fails to generate a response.
Behind the scenes, the constructor calls the following:
self.importScripts (if importScripts is not undefined)
serwist.enableNavigationPreload (if navigationPreload is set to true)
serwist.setCacheNameDetails (if cacheId is not undefined)
self.skipWaiting in the following situations:
skipWaiting is set to true."SKIP_WAITING" is sent to the service worker.serwist.clientsClaim (if clientsClaim is set to true)
serwist.PrecacheFallbackPlugin (if runtimeCaching and fallbacks are not undefined)
serwist.initializeGoogleAnalytics (if offlineAnalyticsConfig is set)
serwist.disableDevLogs (if disableDevLogs is set to true)
precacheStrategy — The strategy used to precache assets and respond to fetch events.
routes — A Map of HTTP methods ('GET', etc.) to an array of all corresponding registered Route instances.
addEventListeners() — Adds Serwist’s event listeners for you. Before calling it, add your own listeners should you need to.
addToPrecacheList(entries) — Adds items to the precache list, removing duplicates and ensuring the information is valid.
handleInstall(event) — Precaches new and updated assets. Call this method from the service worker’s install event.
handleActivate(event) — Deletes assets that are no longer present in the current precache manifest. Call this method from the service worker’s activate event.
handleFetch(event) — Gets a Response from an appropriate Route’s handler. Call this method from the service worker’s fetch event.
handleCache(event) — Caches new URLs on demand. Call this method from the service worker’s message event. To trigger the handler, send a message of type "CACHE_URLS" alongside a list of URLs that should be cached as urlsToCache.
setDefaultHandler(handler, method) — Define a default handler that’s called when no routes explicitly match the incoming request.
setCatchHandler(handler) — If a Route throws an error while handling a request, this handler will be called and given a chance to provide a response.
registerCapture(capture, handler?, method?) — Registers a RegExp, string, or function with a caching strategy to the router.
registerRoute(route) — Registers a Route with the router.
unregisterRoute(route) — Unregisters a Route with the router.
getUrlsToPrecacheKeys() — Returns a mapping of a precached URL to the corresponding cache key, taking into account the revision information for the URL.
getPrecachedUrls() — Returns a list of all the URLs that have been precached by the current service worker.
getPrecacheKeyForUrl(url) — Returns the cache key used for storing a given URL. If that URL is unversioned, like “/index.html”, then the cache key will be the original URL with a search parameter appended to it.
getIntegrityForPrecacheKey(cacheKey) — Retrieves the subresource integrity associated with the cache key, or undefined if it’s not set.
matchPrecache(request) — This acts as a drop-in replacement for cache.match() with the following differences:
createHandlerBoundToUrl(url) — Returns a function that looks up url in the precache (taking into account revision information), and returns the corresponding Response.
handleRequest({ request, event }) — Applies the routing rules to a FetchEvent object to get a Response from an appropriate Route’s handler.
findMatchingRoute({ url, sameOrigin, request, event }) — Checks a request and URL (and optionally an event) against the list of registered routes, and if there’s a match, returns the corresponding route along with any params generated by the match.
sw.ts
import type { PrecacheEntry, SerwistGlobalConfig } from "serwist";
import { Serwist } from "serwist";
// This import depends on your framework. For example, if you use Next.js, it should
// be @serwist/next/worker rather than @serwist/vite/worker.
import { defaultCache } from "@serwist/vite/worker";
declare global {
interface WorkerGlobalScope extends SerwistGlobalConfig {
// Change this attribute's name to your `injectionPoint`.
// `injectionPoint` is an InjectManifest option.
// See https://serwist.pages.dev/docs/build/configuring
__SW_MANIFEST: (PrecacheEntry | string)[] | undefined;
}
}
declare const self: ServiceWorkerGlobalScope;
const serwist = new Serwist({
precacheEntries: self.__SW_MANIFEST,
skipWaiting: true,
clientsClaim: true,
navigationPreload: true,
disableDevLogs: true,
runtimeCaching: defaultCache,
});
serwist.addEventListeners();