Configuration Schema

Full schema at https://swoff.netlify.app/schema/v1.json.

Root

Field	Type	Default	Description
`$schema`	string	`"https://swoff.netlify.app/schema/v1.json"`	JSON Schema URL for IDE autocompletion
`enabled`	boolean	`true`	Enable config-driven SW generation. Set `false` to write your own SW manually
`version`	string	`"from-package"`	SW version. Use `"from-package"` to read from `package.json`, or specify semver like `"1.0.0"`
`minSupportedVersion`	string	`"0.0.0"`	Force update for clients running older versions

serviceWorker

Field	Type	Default	Description
`autoRegister`	boolean	`true`	Auto-register new SW versions on page load. Set `false` for consent-based registration
`autoActivate`	boolean	`false`	Auto-activate new SW via `skipWaiting`. Only applies when `autoRegister` or `handleUpdateApproved()` registers a new version

`serviceWorker.strategy`

Field	Type	Default	Description
`default`	string	`"cache-first"`	Default caching strategy for unmatched routes
`patterns`	object	`{}`	Per-URL pattern strategy overrides
`mode`	string	`"all"`	Controls which requests are processed by the SW cache strategy system. `"all"` processes every GET/HEAD request. `"explicit-only"` only processes requests with `X-SW-Cache-Strategy` header
`clearRuntimeOnUpdate`	boolean	`false`	Delete runtime cache on SW activate. Use as a security measure — cached API responses are cleared on every SW update, preventing poisoned data from persisting
`normalizeKey`	boolean	`false`	Normalize cache keys by lowercasing and sorting query params. Reduces cache fragmentation
`ignoreQueryParams`	string[]	`[]`	Query parameter names to ignore when matching cache keys. Useful for Analytics/UTM params that should not create separate cache entries

`serviceWorker.navigation`

Field	Type	Default	Description
`mode`	string	`"spa"`	How navigation requests are handled. `"spa"` falls back to `fallback` on cache miss. `"default"` uses the strategy as-is
`preload`	boolean	`true`	Enable Navigation Preload API in the service worker. Reduces startup latency for navigation requests
`fallback`	string	`"/index.html"`	Fallback URL for navigation requests when `navigation.mode` is `"spa"`

Strategy Values

cache-first — Serve from cache, fall back to network
network-first — Try network, fall back to cache
stale-while-revalidate — Serve cached, refresh in background
cache-only — Cache only (never network)
network-only — Network only (never cache)

features

All features are nested under the features key.

Boolean Features

Field	Type	Default	Description
`versionedSw`	boolean	`true`	Versioned SW lifecycle (install, activate, skipWaiting)
`mutationQueue`	boolean	`false`	Queue offline writes, sync on reconnect
`backgroundSync`	boolean	`false`	Background Sync API (Chrome/Edge only). Requires `mutationQueue: true`
`crossTabSync`	boolean	`true`	Cross-tab cache invalidation via postMessage. Requires `tagInvalidation: true`
`tagInvalidation`	boolean	`true`	URL-based cache tag generation
`clientRegistration`	boolean	`true`	Generate `sw-injector.js` with version checking and update consent

Object Features

pwa

Field	Type	Default	Description
`enabled`	boolean	`true`	Generate PWA install handler + manifest.json
`preventDefaultInstall`	boolean	`false`	Suppress native install prompt. When `true`, dev must call `promptInstall()` manually

auth

Field	Type	Default	Description
`enabled`	boolean	`false`	Generate auth integration (auth-store, auth-fetch, auth-user, auth-state)
`type`	string	`"bearer"`	Auth mechanism. `"cookie"` — httpOnly cookies (auto-sent by browser). `"bearer"` — bearer token in memory only. `"custom"` — implement your own `withAuthHeaders()`
`refreshPath`	string	`"/api/refresh"`	Token refresh endpoint path
`userEndpoint`	string	`"/api/me"`	User info endpoint path

indexeddb

Field	Type	Default	Description
`enabled`	boolean	`false`	Generate IndexedDB storage patterns
`name`	string	`"app-db"`	IndexedDB database name
`stores`	array	`[]`	Array of object store names (user defines their own schema)

build

Field	Type	Default	Description
`outputDir`	string	`"dist"`	Build output directory for SW + version.json
`swFilename`	string	`"sw"`	SW filename (without version). Produces `<swFilename>-v<version>.js`

Manifest

The CLI generates public/manifest.json when features.pwa.enabled is true, but only if:

The public/ directory exists at project root
No public/manifest.json already exists

The generated manifest includes full PWA fields (name, short_name, icons, start_url, display, background_color, theme_color, description, scope, categories, lang, orientation).

Example Config

{
  "$schema": "https://swoff.netlify.app/schema/v1.json",
  "enabled": true,
  "version": "from-package",
  "minSupportedVersion": "1.0.0",
  "serviceWorker": {
    "autoRegister": true,
    "autoActivate": false,
    "strategy": {
      "default": "cache-first",
      "patterns": {
        "/api/*": "network-first",
        "/static/*": "cache-first"
      },
      "mode": "all",
      "clearRuntimeOnUpdate": false,
      "normalizeKey": false,
      "ignoreQueryParams": []
    },
    "navigation": {
      "mode": "spa",
      "preload": true,
      "fallback": "/index.html"
    }
  },
  "features": {
    "versionedSw": true,
    "mutationQueue": false,
    "backgroundSync": false,
    "pwa": { "enabled": true, "preventDefaultInstall": false },
    "auth": { "enabled": false, "type": "bearer", "refreshPath": "/api/refresh", "userEndpoint": "/api/me" },
    "crossTabSync": true,
    "tagInvalidation": true,
    "clientRegistration": true,
    "indexeddb": { "enabled": false, "name": "app-db", "stores": [] }
  },
  "build": {
    "outputDir": "dist",
    "swFilename": "sw"
  }
}

Validation

Validate your config against the schema:

npx @swoff/cli validate

Schema Reference