Skip to content
@staticbolt/core

Service Worker Plugin

A staticbolt plugin that uses Workbox to generate a precaching service worker for your site at build time. The service worker precaches every matched output file so your site works offline. The plugin only runs during production builds.

Installation

The plugin ships as part of @staticbolt/core. You do not need to install anything else.

Usage

In your .staticbolt.ts configuration file:

import { defineConfig } from "@staticbolt/core";
import { serviceWorkerPlugin } from "@staticbolt/core/plugins";


export default defineConfig({
  plugins: [serviceWorkerPlugin()],
});

Registering the service worker

The plugin generates the service worker file but does not register it. Register it yourself in your client-side JavaScript with workbox-window.

import { Workbox } from "workbox-window";


if ("serviceWorker" in navigator && _production) {
  const wb = new Workbox("/sw.js");
  wb.register();
}

The _production variable is a build-time constant from staticbolt. With that check, the service worker is only registered in production.

Plugin Options

swDest

  • Type: string
  • Default: "sw.js"

The output path for the generated service worker file, relative to the build output directory.

globPatterns

  • Type: string[]
  • Default: ["**/*.{js,wasm,css,html}"]

Glob patterns for files to precache.

globIgnores

  • Type: string[]
  • Default: ["**/node_modules/**/*"]

Glob patterns for files to exclude from precaching.

maximumFileSizeToCacheInBytes

  • Type: number
  • Default: 2097152 (2 MB)

A file larger than this is left out of the precache.

skipWaiting

  • Type: boolean
  • Default: false

When true, the new service worker activates immediately without waiting for existing tabs to close.

clientsClaim

  • Type: boolean
  • Default: false

When true, the service worker takes control of all available clients as soon as it activates.

cleanupOutdatedCaches

  • Type: boolean
  • Default: false

Removes caches from previous service worker versions during activation.

cacheId

  • Type: string

A cache identifier for versioning. Useful when you run several sites on the same origin.

inlineWorkboxRuntime

  • Type: boolean
  • Default: false

When true, the Workbox runtime is inlined into the generated service worker file instead of being loaded separately.

offlineGoogleAnalytics

  • Type: boolean
  • Default: false

Enables offline Google Analytics support. Events are queued while offline and replayed once the connection is back.

sourcemap

  • Type: boolean
  • Default: true

Generates source maps for the service worker file.

directoryIndex

  • Type: string

The default directory index file name for cached URLs (for example "index.html").

modifyURLPrefix

  • Type: Record<string, string>

Rewrites URL prefixes for cached assets. Useful when your output directory structure does not match the URL structure of your site.

globFollow

  • Type: boolean
  • Default: true

Whether to follow symbolic links when matching glob patterns.