Serwist

https://serwist.pages.dev/docs
Admin
Serwist is a collection of JavaScript libraries for progressive web apps, forked from Workbox to...
Tokens:77,917
Snippets:665
Trust Score:7.2
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Initialize a new project with npx degit

Source: https://serwist.pages.dev/docs/next

Scaffolds a new Next.js project with Serwist using the next-basic example template. Run this command when initializing a new project to get a working setup.

```bash
npx degit serwist/serwist/examples/next-basic my-app
```

--------------------------------

### Install Serwist with npm

Source: https://serwist.pages.dev/docs/next/getting-started

Run this command to install the Serwist Next.js plugin and the serwist development dependency. This is the webpack quick start installation step.

```bash
npm i @serwist/next && npm i -D serwist
```

--------------------------------

### Initialize Nuxt project with Serwist using npx degit

Source: https://serwist.pages.dev/docs/nuxt

Initializes a new Nuxt project with Serwist by cloning the nuxt-basic example template. Run this command when starting a new project.

```bash
npx degit serwist/serwist/examples/nuxt-basic my-app
```

--------------------------------

### Serwist service worker setup (sw.ts)

Source: https://serwist.pages.dev/docs/serwist/core/serwist

Example service worker file (sw.ts) for Serwist. It imports Serwist and defaultCache, declares the global __SW_MANIFEST injection point, and configures the Serwist instance with precacheEntries, skipWaiting, clientsClaim, navigationPreload, disableDevLogs, and runtimeCaching. Finally, it calls addEventListeners().

```typescript
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();
```

--------------------------------

### Install @serwist/window with npm

Source: https://serwist.pages.dev/docs/window

Install the @serwist/window package as a development dependency using npm.

```bash
npm i -D @serwist/window
```

--------------------------------

### Install @serwist packages

Source: https://serwist.pages.dev/docs/vite/recipes/svelte

Install the required Serwist packages for SvelteKit integration.

```bash
npm i -D @serwist/build @serwist/vite @serwist/window serwist
```

--------------------------------

### Install Serwist packages with npm

Source: https://serwist.pages.dev/docs/webpack-plugin/getting-started

Install the required Serwist packages as dev dependencies using npm. The command is shown in the Install section.

```bash
npm i -D @serwist/webpack-plugin @serwist/window serwist
```

--------------------------------

### Install Serwist packages

Source: https://serwist.pages.dev/docs/nuxt/getting-started

Install the required packages for Serwist in a Nuxt project.

```bash
npm i -D @serwist/nuxt @serwist/vite serwist
```

--------------------------------

### handleInstall(event)

Source: https://serwist.pages.dev/docs/serwist/core/serwist

Precaches new and updated assets. Call this method from the service worker's install event.

```APIDOC
## handleInstall(event)

### Description
Precaches new and updated assets. Call this method from the service worker's install event.

### Method
handleInstall

### Parameters
- **event** (ExtendableEvent) - Required - The install event.

### Returns
Promise that resolves when precaching is complete.

```

--------------------------------

### Install Serwist Turbopack packages

Source: https://serwist.pages.dev/docs/next/turbo

Install the required packages for using Serwist with Turbopack. The -D flag installs them as dev dependencies.

```bash
npm i -D @serwist/turbopack esbuild serwist
```

--------------------------------

### Install @serwist/cli with npm

Source: https://serwist.pages.dev/docs/cli

Install the @serwist/cli package as a dev dependency using npm.

```bash
npm i -D @serwist/cli
```

--------------------------------

### Install Serwist packages with npm

Source: https://serwist.pages.dev/docs/vite/getting-started

Install the required Serwist packages for Vite. Use this command in your project directory. The -D flag saves them as dev dependencies.

```bash
npm i -D @serwist/vite @serwist/window serwist
```

--------------------------------

### Install Serwist configurator mode dependencies

Source: https://serwist.pages.dev/docs/next/config

Installs the required packages for Serwist's configurator mode. This command must be run in the terminal.

```bash
npm i -D @serwist/next @serwist/cli serwist esbuild concurrently
```

--------------------------------

### PrecacheRoute

Source: https://serwist.pages.dev/docs/serwist/runtime-caching/routing/precache-route

Documentation for the PrecacheRoute class, including its constructor parameters and usage example.

```APIDOC
## PrecacheRoute

### Description
A subclass of `Route` that takes a `Serwist` instance and uses it to match incoming requests and handle fetching responses from the precache.

### Constructor Parameters
- **serwist** (Serwist) - Required - A `Serwist` instance used to both match requests and respond to `fetch` events.
- **options** (Object) - Optional - Options to control how requests are matched against the list of precached URLs.
  - **directoryIndex** (string) - Optional - 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** (Array<RegExp>) - Optional - An array of `RegExp` objects matching search params that should be removed when looking for a precache match.
  - **cleanURLs** (boolean) - Optional - Tells Serwist to check the precache for an entry whose URL is the request URL appended with ".html".
  - **urlManipulation** (function) - Optional - A function that should take a URL and return an array of alternative URLs that should be checked for precache matches.

### Usage Example
```typescript
import { Serwist } from "serwist";

const serwist = new Serwist({
  // `PrecacheRoute` is automatically registered for you!
  precacheEntries: self.__SW_MANIFEST,
});

serwist.addEventListeners();
```
```

--------------------------------

### NavigationRoute

Source: https://serwist.pages.dev/docs/serwist/runtime-caching/routing/navigation-route

Documentation for the NavigationRoute class, including its constructor parameters and usage example.

```APIDOC
## NavigationRoute

### Description
`NavigationRoute` makes it easy to create a `Route` object that matches navigation requests. It will only match incoming Requests whose mode is set to `"navigate"`. You can optionally only apply this route to a subset of navigation requests by using one or both of the `denylist` and `allowlist` parameters. If both `denylist` and `allowlist` are provided, `denylist` will take precedence. The regular expressions in `allowlist` and `denylist` are matched against the concatenated pathname and search portions of the requested URL.

### Constructor
`new NavigationRoute(handler, options)`

### Parameters
- **handler** (function) - Required - A callback function that returns a `Promise` resolving to a `Response`.
- **options** (object) - Optional - Options for `NavigationRoute`:
  - **allowlist** (RegExp[]) - Optional - A list of `RegExp` objects matching URLs that should match this route.
  - **denylist** (RegExp[]) - Optional - A list of `RegExp` objects matching URLs that should not match this route.

### Usage Example
```typescript
// Example: handling all navigations using an app shell.
import { NavigationRoute, Serwist } from "serwist";

const serwist = new Serwist({
  // Assuming that your precache list includes "/app-shell.html".
  precacheEntries: self.__SW_MANIFEST,
});

// This assumes that "/app-shell.html" has been precached.
serwist.registerRoute(new NavigationRoute(serwist.createHandlerBoundToUrl("/app-shell.html")));

serwist.addEventListeners();
```
```

--------------------------------

### Scaffold a Vite + React project with Serwist

Source: https://serwist.pages.dev/docs/vite

Use this command to scaffold a new Vite + React project with Serwist preconfigured. It clones the vite-react-basic example from the Serwist repository into a directory named my-app.

```bash
npx degit serwist/serwist/examples/vite-react-basic my-app
```

--------------------------------

### StrategyHandler

Source: https://serwist.pages.dev/docs/serwist/runtime-caching/caching-strategies/strategy-handler

Documentation for the StrategyHandler class, including its fields, methods, and usage example.

```APIDOC
## StrategyHandler

### Description
A class created every time a Strategy instance calls `Strategy.handle` or `Strategy.handleAll` that wraps all fetch and cache actions around plugin callbacks and keeps track of when the strategy is "done" (i.e. when all added `event.waitUntil()` promises have resolved).

### Methods and fields
- `event` — The event associated with this request.
- `request` — The request the strategy is processing (passed to the strategy's `handle()` or `handleAll()` method).
- `url` — A `URL` instance of `request.url` (if passed to the strategy's `handle()` or `handleAll()` method). Note: the `url` param will be present if the strategy is invoked from a `Route` object.
- `params` — Some additional params (if passed to the strategy's `handle()` or `handleAll()` method). Note: the `params` param will be present if the strategy is invoked from a `Route` object and that route's matcher returned a truthy value (it will be that value).
- `async fetch(requestInfo)` — Fetches a given request (and invokes any applicable plugin callback methods), taking the `fetchOptions` (for non-navigation requests) and `plugins` provided to the `Strategy` object into account.
- `async fetchAndCachePut(requestInfo)` — Calls `this.fetch()` and (in the background) caches the generated response. The call to `this.cachePut()` automatically invokes `this.waitUntil()`, so you do not have to call `waitUntil()` yourself.
- `async cacheMatch(key)` — Matches a request from the cache (and invokes any applicable plugin callback method) using the `cacheName`, `matchOptions`, and `plugins` provided to the `Strategy` object. The following lifecycle methods are invoked when using this method: 
  - `cacheKeyWillBeUsed`
  - `cachedResponseWillBeUsed`
- `async cachePut(key, response)` — Puts a request/response pair into the cache (and invokes any applicable plugin callback method) using the `cacheName` and `plugins` provided to the `Strategy` object. The following plugin lifecycle methods are invoked when using this method: 
  - `cacheKeyWillBeUsed`
  - `cacheWillUpdate`
  - `cacheDidUpdate`
- `async getCacheKey(request, mode)` — Checks the `plugins` provided to the `Strategy` object for `cacheKeyWillBeUsed` callbacks and executes found callbacks in sequence. The final `Request` object returned by the last plugin is treated as the cache key for cache reads and/or writes. If no `cacheKeyWillBeUsed` plugin callbacks have been registered, the passed request is returned unmodified.
- `hasCallback(name)` — Returns `true` if the strategy has at least one plugin with the given callback.
- `async runCallbacks(name, param)` — Runs all plugin callbacks matching the given name, in order, passing the given `param` object (merged with the plugin's current state) as the only argument.
- `*iterateCallbacks(name)` — Accepts a callback name and returns an iterable of matching plugin callbacks.
- `waitUntil(promise)` — Adds a promise to the extend lifetime promises of the event event associated with the request being handled (usually a `FetchEvent`).
- `async doneWaiting()` — Returns a promise that resolves once all promises passed to `this.waitUntil()` have settled. Note: any work done after `doneWaiting()` settles should be manually passed to an event's `waitUntil()` method (not `this.waitUntil()`), otherwise the service worker thread may be killed prior to your work completing.
- `destroy()` — Stops running the strategy and immediately resolves any pending `waitUntil()` promise.

### Usage
```ts
import { Strategy, type StrategyHandler } from "serwist";

class CacheNetworkRace extends Strategy {
  _handle(request: Request, handler: StrategyHandler) {
    const fetchAndCachePutDone = handler.fetchAndCachePut(request);
    const cacheMatchDone = handler.cacheMatch(request);

    return new Promise<Response>((resolve, reject) => {
      fetchAndCachePutDone.then(resolve);
      cacheMatchDone.then((response) => {
        if (response) {
          resolve(response);
        }
      });

      // Reject if both network and cache error or find no response.
      Promise.allSettled([fetchAndCachePutDone, cacheMatchDone]).then((results) => {
        const [fetchAndCachePutResult, cacheMatchResult] = results;
        if (fetchAndCachePutResult.status === "rejected" && (cacheMatchResult.status === "rejected" || !cacheMatchResult.value)) {
          reject(fetchAndCachePutResult.reason);
        }
      });
    });
  }
}
```
```

--------------------------------

### disableNavigationPreload()

Source: https://serwist.pages.dev/docs/serwist/core/disable-navigation-preload

Documentation for the disableNavigationPreload function from the Serwist library, including its signature and usage example.

```APIDOC
## disableNavigationPreload()

### Description
Disables navigation preloading in the service worker if the browser supports it. This function is part of the Serwist library and is used to turn off the automatic preloading of navigation requests.

### Method
Function

### Signature
`disableNavigationPreload(): Promise<void>`

### Parameters
None

### Return Value
- **Promise<void>** - Resolves when the navigation preload has been disabled.

### Usage Example
```typescript
import { disableNavigationPreload } from "serwist";

await disableNavigationPreload();
```
```

--------------------------------

### Using defaultCache in a service worker

Source: https://serwist.pages.dev/docs/next/worker-exports

Shows how to import defaultCache from @serwist/next/worker and use it in a Serwist instance. The example includes the required global type declaration for __SW_MANIFEST and sets up runtime caching with defaultCache.

```typescript
import { defaultCache } from "@serwist/next/worker";
import type { PrecacheEntry, SerwistGlobalConfig } from "serwist";
import { Serwist } from "serwist";

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,
  runtimeCaching: defaultCache,
});

serwist.addEventListeners();
```

--------------------------------

### CacheOnly

Source: https://serwist.pages.dev/docs/serwist/runtime-caching/caching-strategies/cache-only

Documentation for the CacheOnly caching strategy class, including its constructor parameters and usage example.

```APIDOC
## CacheOnly

### Description
An implementation of the cache only request strategy. This class is useful if you already have your own precaching step. If there is no cache match, this will throw a `SerwistError` exception.

### Constructor Parameters
- **cacheName** (string) - Optional - Cache name to store and retrieve requests. Defaults to Serwist's default cache names.
- **plugins** (Array) - Optional - Plugins to use in conjunction with this caching strategy.
- **fetchOptions** (RequestInit) - Optional - Options passed to non-navigation `fetch()` calls made by this strategy.
- **matchOptions** (CacheQueryOptions) - Optional - The CacheQueryOptions passed to any `cache.match()` or `cache.put()` call made by this strategy.

### Usage Example
```typescript
import { CacheOnly, Serwist } from "serwist";

const serwist = new Serwist({
  runtimeCaching: [
    {
      matcher: ({ url }) => url.pathname.startsWith("/app/v2/"),
      handler: new CacheOnly(),
    },
  ],
});
```
```

--------------------------------

### NetworkOnly

Source: https://serwist.pages.dev/docs/serwist/runtime-caching/caching-strategies/network-only

Documentation for the NetworkOnly caching strategy class, including its constructor parameters and usage example.

```APIDOC
## NetworkOnly

### Description
An implementation of the network only request strategy. This class is useful if you require specific requests to only be fulfilled from the network. If the network request fails, this will throw a `SerwistError` exception.

### Constructor Parameters
- **plugins** (Plugins[]) - Optional - Plugins to use in conjunction with this caching strategy.
- **fetchOptions** (RequestInit) - Optional - Options passed to non-navigation `fetch()` calls made by this strategy.
- **networkTimeoutSeconds** (number) - Optional - If set, any network requests that fail to respond within the timeout will fallback to the cache.

### Usage
```typescript
import { NetworkOnly, Serwist } from "serwist";

const serwist = new Serwist({
  runtimeCaching: [
    {
      matcher: ({ url }) => url.pathname.startsWith("/admin/"),
      handler: new NetworkOnly(),
    },
  ],
});
```
```

--------------------------------

### NetworkFirst usage in sw.ts

Source: https://serwist.pages.dev/docs/serwist/runtime-caching/caching-strategies/network-first

Example of using NetworkFirst in a Serwist service worker. The handler is applied to requests matching the matcher function, which checks if the URL pathname starts with '/social-timeline/'.

```typescript
import { NetworkFirst, Serwist } from "serwist";

const serwist = new Serwist({
  runtimeCaching: [
    {
      matcher: ({ url }) => url.pathname.startsWith("/social-timeline/"),
      handler: new NetworkFirst(),
    },
  ],
});
```

--------------------------------

### Send messages between window and service worker with Serwist

Source: https://serwist.pages.dev/docs/window

Example of sending messages from the window to the service worker and getting a response back. The first block is the `message` event listener in the service worker (index.ts), and the second block uses the `Serwist` class to send the message and wait for the response (sw.ts).

```typescript
serwist.addEventListener("waiting", () => {
  serwist.addEventListener("controlling", location.reload);
  // This code assumes your app has a `confirmUpdate()` method
  // that returns `true` if the user wants to update.
  if (confirmUpdate()) {
    serwist.messageSkipWaiting();
  }
});
```

```typescript
const SW_VERSION = "1.0.0";

self.addEventListener("message", (event) => {
  if (event.data && event.data.type === "GET_VERSION") {
    event.ports[0]?.postMessage(SW_VERSION);
  }
});
```

--------------------------------

### Run the Serwist configuration wizard

Source: https://serwist.pages.dev/docs/cli

Run the configuration wizard to generate a config file based on answers to questions.

```bash
npx @serwist/cli wizard
```

--------------------------------

### Serwist

Source: https://serwist.pages.dev/docs/serwist/core/serwist

Documentation for the Serwist class constructor options.

```APIDOC
## Serwist

### Description
A class that helps bootstrap the service worker.

### Constructor Options

#### precacheEntries
- **Type**: `string[]` (URLs)
- **Required**: No
- **Description**: A list of URLs that should be cached.

#### precacheOptions
- **Type**: `object`
- **Required**: No
- **Description**: Options to customize how Serwist precaches the URLs in the precache list.
  - `cacheName` (string) - Cache name to store and retrieve requests. Defaults to Serwist’s default cache names.
  - `plugins` (array) - Plugins to use when precaching as well as responding to `fetch` events for precached assets.
  - `fetchOptions` (object) - Options passed to non-navigation `fetch()` calls made by this strategy.
  - `matchOptions` (CacheQueryOptions) - The CacheQueryOptions passed to any `cache.match()` or `cache.put()` call made by this strategy.
  - `fallbackToNetwork` (boolean) - Whether to attempt to get the response from the network if there’s a precache miss.
  - `directoryIndex` (string) - 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` (RegExp[]) - An array of `RegExp` objects matching search params that should be removed when looking for a precache match.
  - `cleanURLs` (boolean) - Tells Serwist to check the precache for an entry whose URL is the request URL appended with ".html".
  - `urlManipulation` (function) - A function that should take a URL and return an array of alternative URLs that should be checked for precache matches.
  - `cleanupOutdatedCaches` (boolean) - Whether outdated caches should be removed.
  - `concurrency` (number) - The number of precache requests that should be made concurrently.
  - `navigateFallback` (string) - An URL that should point to a HTML file with which navigation requests for URLs that aren’t precached will be fulfilled.
  - `navigateFallbackAllowlist` (RegExp[]) - URLs that should be allowed to use the `navigateFallback` handler.
  - `navigateFallbackDenylist` (RegExp[]) - URLs that should not be allowed to use the `navigateFallback` handler. This takes precedence over `navigateFallbackAllowlist`.

#### skipWaiting
- **Type**: `boolean`
- **Required**: No
- **Description**: Forces the waiting service worker to become the active one.

#### importScripts
- **Type**: `string[]`
- **Required**: No
- **Description**: Imports external scripts. They are executed in the order they are passed.

#### navigationPreload
- **Type**: `boolean`
- **Required**: No
- **Description**: Enables navigation preloading if it is supported.

#### cacheId
- **Type**: `string`
- **Required**: No
- **Description**: Modifies the prefix of the default cache names used by Serwist packages.

#### clientsClaim
- **Type**: `boolean`
- **Required**: No
- **Description**: Claims any currently available clients once the service worker becomes active. This is normally used in conjunction with `skipWaiting()`.

#### runtimeCaching
- **Type**: `array`
- **Required**: No
- **Description**: A list of caching strategies.

#### offlineAnalyticsConfig
- **Type**: `object`
- **Required**: No
- **Description**: Your configuration for `initializeGoogleAnalytics`. This plugin is only initialized when this option is not `undefined` or `false`.

#### disableDevLogs
- **Type**: `boolean`
- **Required**: No
- **Description**: Disables Serwist’s logging in development mode.

#### fallbacks
- **Type**: `object`
- **Required**: No
- **Description**: Precaches routes so that they can be used as a fallback when a `Strategy` fails to generate a response.
```

--------------------------------

### Run build command

Source: https://serwist.pages.dev/docs/cli

Bundle a service worker file with a precache manifest injected using esbuild.

```bash
npx @serwist/cli build
```

--------------------------------

### Initialize Serwist service worker

Source: https://serwist.pages.dev/docs/serwist/core

Minimal setup for a Serwist service worker. Imports `defaultCache` from `@serwist/vite/worker` and `Serwist` from `serwist`, declares the global `__SW_MANIFEST` type, and initializes the service worker with precache entries and runtime caching. Call `serwist.addEventListeners()` to activate the service worker.

```typescript
// Where you import this depends on your stack.
import { defaultCache } from "@serwist/vite/worker";
import { type PrecacheEntry, Serwist } from "serwist";

declare global {
  interface WorkerGlobalScope {
    __SW_MANIFEST: (PrecacheEntry | string)[] | undefined;
  }
}

declare const self: ServiceWorkerGlobalScope;

const serwist = new Serwist({
  precacheEntries: self.__SW_MANIFEST,
  runtimeCaching: defaultCache,
});

serwist.addEventListeners();
```

--------------------------------

### get name()

Source: https://serwist.pages.dev/docs/serwist/core/background-sync-queue

Returns the unique name of the queue.

```APIDOC
## Getter: get name()

### Description
Returns the unique name for this queue.

### Returns
- **string** - The unique name of the queue.
```

--------------------------------

### BroadcastUpdatePlugin

Source: https://serwist.pages.dev/docs/serwist/runtime-caching/plugins/broadcast-update-plugin

Documentation for the BroadcastUpdatePlugin class, including its purpose and usage example.

```APIDOC
## BroadcastUpdatePlugin

### Description
A class implementing the `cacheDidUpdate` lifecycle callback. It will automatically broadcast a message whenever a cached response is updated.

### Usage
```typescript
import { BroadcastUpdatePlugin, StaleWhileRevalidate } from "serwist";

serwist.registerCapture(
  ({ url }) => url.pathname.startsWith("/api/"),
  new StaleWhileRevalidate({
    plugins: [new BroadcastUpdatePlugin()],
  }),
);
```

### Options
See BroadcastCacheUpdate’s options.
```

--------------------------------

### Add metadata and SerwistProvider to layout

Source: https://serwist.pages.dev/docs/next/turbo

Add this content to `app/layout.tsx` and/or `pages/_app.tsx`. It sets up metadata, viewport, and wraps the app with `SerwistProvider`.

```tsx
import { SerwistProvider } from "@serwist/turbopack/react";
import type { Metadata, Viewport } from "next";
import type { ReactNode } from "react";

const APP_NAME = "PWA App";
const APP_DEFAULT_TITLE = "My Awesome PWA App";
const APP_TITLE_TEMPLATE = "%s - PWA App";
const APP_DESCRIPTION = "Best PWA app in the world!";

export const metadata: Metadata = {
  applicationName: APP_NAME,
  title: {
    default: APP_DEFAULT_TITLE,
    template: APP_TITLE_TEMPLATE,
  },
  description: APP_DESCRIPTION,
  appleWebApp: {
    capable: true,
    statusBarStyle: "default",
    title: APP_DEFAULT_TITLE,
    // startUpImage: [],
  },
  formatDetection: {
    telephone: false,
  },
  openGraph: {
    type: "website",
    siteName: APP_NAME,
    title: {
      default: APP_DEFAULT_TITLE,
      template: APP_TITLE_TEMPLATE,
    },
    description: APP_DESCRIPTION,
  },
  twitter: {
    card: "summary",
    title: {
      default: APP_DEFAULT_TITLE,
      template: APP_TITLE_TEMPLATE,
    },
    description: APP_DESCRIPTION,
  },
};

export const viewport: Viewport = {
  themeColor: "#FFFFFF",
};

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" dir="ltr">
      <head />
      <body>
        <SerwistProvider swUrl="/serwist/sw.js">{children}</SerwistProvider>
      </body>
    </html>
  );
}
```

--------------------------------

### Set up Serwist with PrecacheRoute in sw.ts

Source: https://serwist.pages.dev/docs/serwist/runtime-caching/routing/precache-route

Create a Serwist instance with precacheEntries set to self.__SW_MANIFEST. PrecacheRoute is automatically registered, so no explicit route registration is needed. Call addEventListeners() to set up the service worker event listeners.

```typescript
import { Serwist } from "serwist";

const serwist = new Serwist({
  // `PrecacheRoute` is automatically registered for you!
  precacheEntries: self.__SW_MANIFEST,
});

serwist.addEventListeners();
```

--------------------------------

### StorableRequest

Source: https://serwist.pages.dev/docs/serwist/core/storable-request

Documentation for the StorableRequest class, including its constructor, methods, and usage example.

```APIDOC
## StorableRequest

### Description
A class to make it easier to serialize and de-serialize requests so they can be stored in IndexedDB. Most developers will not need to access this class directly; it is exposed for advanced use cases.

### Constructor

#### Parameters
- `requestData` (object) - Required - An object of request data that includes the `url` plus any relevant property of `requestInit`.

### Methods

#### `static async fromRequest(request)`
Converts a `Request` object to a plain object that can be structured cloned or stringified to JSON.

#### `toObject()`
Returns a deep clone of the instance's `requestData` object.

#### `toRequest()`
Converts this instance to a `Request`.

#### `clone()`
Creates and returns a deep clone of the instance.

### Usage Example
```ts
import { StorableRequest } from "serwist";

const storableRequest = await StorableRequest.fromRequest(request);

// This object can be saved in IndexedDB.
const objectRequest = storableRequest.toObject();

const parsedRequest = new StorableRequest(objectRequest).toRequest();
```
```

--------------------------------

### Configure Vite with custom Serwist build plugin

Source: https://serwist.pages.dev/docs/vite/recipes/svelte

Create a Vite plugin that integrates @serwist/vite with SvelteKit, including a custom build plugin that runs during the server build.

```typescript
import crypto from "node:crypto";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { errors } from "@serwist/build";
import { createApi, createContext, dev as devPlugin, main as mainPlugin } from "@serwist/vite";
import type { PluginOptions, SerwistViteApi, SerwistViteContext } from "@serwist/vite";
import { sveltekit } from "@sveltejs/kit/vite";
import type { Plugin } from "vite";
import { defineConfig } from "vite";
import config from "./svelte.config";

// Source: https://github.com/sveltejs/kit/blob/6419d3eaa7bf1b0a756b28f06a73f71fe042de0a/packages/kit/src/utils/filesystem.js
// License: MIT
/**
 * Resolves a file path without extension. Also handles `/index` if the path
 * actually points to a directory.
 * @param ctx
 * @param api
 * @returns
 */
const resolveEntry = (entry: string): string | null => {
  if (fs.existsSync(entry)) {
    const stats = fs.statSync(entry);
    if (stats.isDirectory()) {
      return resolveEntry(path.join(entry, "index"));
    }

    return entry;
  }
  const dir = path.dirname(entry);

  if (fs.existsSync(dir)) {
    const base = path.basename(entry);
    const files = fs.readdirSync(dir);

    const found = files.find((file) => file.replace(/\.[^.]+$/, "") === base);

    if (found) return path.join(dir, found);
  }

  return null;
};

// We do not rely on `@serwist/vite`'s built-in `buildPlugin` because
// it runs during the client build, but SvelteKit builds the service worker
// during the server build, which takes place after the client one.
/**
 * Custom Serwist build plugin for your custom SvelteKit integration.
 * @param ctx
 * @param api
 * @returns
 */
const buildPlugin = (ctx: SerwistViteContext, api: SerwistViteApi) => {
  return <Plugin>{
    name: "@serwist/vite:build",
    apply: "build",
    enforce: "pre",
    closeBundle: {
      sequential: true,
      order: ctx.userOptions?.integration?.closeBundleOrder,
      async handler() {
        if (api && !api.disabled && ctx.viteConfig.build.ssr) {
          await api.generateSW();
        }
      },
    },
    buildEnd(error) {
      if (error) throw error;
    },
  };
};
```

--------------------------------

### ExpirationPlugin

Source: https://serwist.pages.dev/docs/serwist/runtime-caching/plugins/expiration-plugin

Documentation for the ExpirationPlugin class, including its constructor options, methods, and usage example.

```APIDOC
## ExpirationPlugin

### Description
A plugin used in a Strategy to regularly enforce a limit on the age and/or the number of cached requests. It can only be used with `Strategy` instances that have a custom `cacheName` property set.

### Constructor Options
- **maxEntries** (number) - Optional - The maximum number of entries to cache. Entries used (if `maxAgeFrom` is `"last-used"`) or fetched from the network (if `maxAgeFrom` is `"last-fetched"`) least recently will be removed as the maximum is reached.
- **maxAgeSeconds** (number) - Optional - The maximum age of an entry before it's treated as stale and removed.
- **maxAgeFrom** (string) - Optional - Determines whether `maxAgeSeconds` should be calculated from when an entry was last fetched or when it was last used.
- **matchOptions** (CacheQueryOptions) - Optional - The CacheQueryOptions that will be used when calling `delete()` on the cache.
- **purgeOnQuotaError** (boolean) - Optional - Whether to opt this cache into automatic deletion if the available storage quota has been exceeded.

### Methods
- **async deleteCacheAndMetadata()** - Deletes the underlying `Cache` instance associated with this instance and the metadata from IndexedDB used to keep track of expiration details.

### Usage Example
```ts
import { CacheFirst, ExpirationPlugin } from "serwist";

serwist.registerCapture(
  ({ request }) => request.destination === "image",
  new CacheFirst({
    cacheName: "image-cache",
    plugins: [
      new ExpirationPlugin({
        maxEntries: 20,
        maxAgeSeconds: 24 * 60 * 60,
      }),
    ],
  }),
);
```
```

--------------------------------

### BackgroundSyncPlugin Constructor

Source: https://serwist.pages.dev/docs/serwist/runtime-caching/plugins/background-sync-plugin

Creates a new BackgroundSyncPlugin instance with a queue name and optional parameters. The parameters are the same as those for BackgroundSyncQueue.

```APIDOC
## BackgroundSyncPlugin

### Description
A class implementing the `fetchDidFail` lifecycle callback. This makes it easier to add failed requests to a `background sync queue`.

### Constructor
`new BackgroundSyncPlugin(queueName, options?)`

### Parameters
- **queueName** (string) - Required - The name of the background sync queue.
- **options** (object) - Optional - See BackgroundSyncQueue's parameters. For example, `maxRetentionTime` (number) - Optional - The maximum time in minutes to retry the request.

### Usage Example
```typescript
import { BackgroundSyncPlugin, NetworkOnly } from "serwist";

const backgroundSync = new BackgroundSyncPlugin("myQueueName", {
  maxRetentionTime: 24 * 60, // Retry for a maximum of 24 Hours (specified in minutes)
});

serwist.registerCapture(
  /\/api\/.*\/*.json/,
  new NetworkOnly({
    plugins: [backgroundSync],
  }),
  "POST",
);
```
```

--------------------------------

### Enable navigation preload and register a navigation route in sw.ts

Source: https://serwist.pages.dev/docs/serwist/core/enable-navigation-preload

Imports enableNavigationPreload, NavigationRoute, and NetworkFirst from 'serwist'. Calls enableNavigationPreload() to enable navigation preloading, then creates a NetworkFirst strategy with cacheName 'cached-navigations' and registers a NavigationRoute with optional allowlist/denylist commented out. The comment notes that NetworkOnly, CacheFirst, or StaleWhileRevalidate can be swapped in as needed.

```TypeScript
import { enableNavigationPreload, NavigationRoute, NetworkFirst } from "serwist";

enableNavigationPreload();

// Swap in NetworkOnly, CacheFirst, or StaleWhileRevalidate as needed.
const navigationStrategy = new NetworkFirst({
  cacheName: "cached-navigations",
});

const navigationRoute = new NavigationRoute(navigationStrategy, {
  // Optionally, provide a allow/denylist of RegExps to determine
  // which paths will match this route.
  // allowlist: [],
  // denylist: [],
});

serwist.registerRoute(navigationRoute);
```

--------------------------------

### Update tsconfig.json for Serwist types

Source: https://serwist.pages.dev/docs/vite/recipes/svelte

Add @serwist/vite/typings to the compilerOptions.types array to get correct types for virtual:serwist.

```json
{
  // Other stuff...
  "compilerOptions": {
    // Other options...
    "types": [
      // Other types...
      // This allows Serwist to correctly type "virtual:serwist".
      "@serwist/vite/typings"
    ],
  },
}
```

--------------------------------

### Create basic service worker with Serwist

Source: https://serwist.pages.dev/docs/next/turbo

Basic service worker template using `Serwist` from `serwist` and `defaultCache` from `@serwist/turbopack/worker`. It sets up precaching, runtime caching, and a fallback for document requests.

```typescript
/// <reference lib="esnext" />
/// <reference lib="webworker" />
import { defaultCache } from "@serwist/turbopack/worker";
import type { PrecacheEntry, SerwistGlobalConfig } from "serwist";
import { Serwist } from "serwist";

// This declares the value of `injectionPoint` to TypeScript.
// `injectionPoint` is the string that will be replaced by the
// actual precache manifest. By default, this string is set to
// `"self.__SW_MANIFEST"`.
declare global {
  interface WorkerGlobalScope extends SerwistGlobalConfig {
    __SW_MANIFEST: (PrecacheEntry | string)[] | undefined;
  }
}

declare const self: ServiceWorkerGlobalScope;

const serwist = new Serwist({
  precacheEntries: self.__SW_MANIFEST,
  skipWaiting: true,
  clientsClaim: true,
  navigationPreload: true,
  runtimeCaching: defaultCache,
  fallbacks: {
    entries: [
      {
        url: "/~offline",
        matcher({ request }) {
          return request.destination === "document";
        },
      },
    ],
  },
});

serwist.addEventListeners();
```

--------------------------------

### handleRequest({ request, event })

Source: https://serwist.pages.dev/docs/serwist/core/serwist

Applies the routing rules to a FetchEvent object to get a Response from an appropriate Route's handler.

```APIDOC
## handleRequest({ request, event })

### Description
Applies the routing rules to a FetchEvent object to get a Response from an appropriate Route's handler.

### Method
handleRequest

### Parameters
- **request** (Request) - Required - The request to handle.
- **event** (FetchEvent) - Optional - The fetch event.

### Returns
Promise<Response> - The response from the matching route's handler.

```

--------------------------------

### Run inject-manifest command

Source: https://serwist.pages.dev/docs/cli

Inject a precache manifest into an existing service worker file, replacing the self.__WB_MANIFEST string by default.

```bash
npx @serwist/cli inject-manifest
```

--------------------------------

### Add BroadcastUpdatePlugin to StaleWhileRevalidate strategy

Source: https://serwist.pages.dev/docs/serwist/guide/broadcasting-updates

Configures the StaleWhileRevalidate strategy with a BroadcastUpdatePlugin to broadcast cache updates for URLs starting with /api/.

```typescript
import { BroadcastUpdatePlugin, StaleWhileRevalidate } from "serwist";

serwist.registerCapture(
  ({ url }) => url.pathname.startsWith("/api/"),
  new StaleWhileRevalidate({
    plugins: [new BroadcastUpdatePlugin()],
  }),
);
```

--------------------------------

### handleFetch(event)

Source: https://serwist.pages.dev/docs/serwist/core/serwist

Gets a Response from an appropriate Route's handler. Call this method from the service worker's fetch event.

```APIDOC
## handleFetch(event)

### Description
Gets a Response from an appropriate Route's handler. Call this method from the service worker's fetch event.

### Method
handleFetch

### Parameters
- **event** (FetchEvent) - Required - The fetch event.

### Returns
Promise<Response> - The response from the matching route's handler.

```

--------------------------------

### new Route(match, handler, method?)

Source: https://serwist.pages.dev/docs/serwist/runtime-caching/routing/route

Creates a new Route instance that pairs a match callback with a handler callback. The match callback determines if the route applies to a request, and the handler returns a Promise resolving to a Response. Optionally specify the HTTP method to match (default GET).

```APIDOC
## [CONSTRUCTOR] new Route(match, handler, method?)

### Description
Creates a new Route instance that pairs a match callback with a handler callback. The match callback determines if the route applies to a request, and the handler returns a Promise resolving to a Response. Optionally specify the HTTP method to match (default GET).

### Parameters
- **match** (function) - Required - A callback function that determines whether the route matches a given fetch event by returning a truthy value.
- **handler** (function) - Required - A callback function that returns a Promise resolving to a Response.
- **method** (string) - Optional - The HTTP method to match the route against. Defaults to `GET`.

### Usage Example
```typescript
import { CacheFirst, Route, Serwist } from "serwist";

const serwist = new Serwist();

serwist.registerRoute(new Route(({ request, sameOrigin }) => {
  return sameOrigin && request.destination === "image";
}, new CacheFirst()));

serwist.addEventListeners();
```
```
Tokens:
Raw