Getting Started with Configuration

Swoff uses a JSON config. Run the CLI to generate the SW and supporting files.

Quick Setup

# Initialize (creates swoff.config.json + swoff/ directory)
npx @swoff/cli init

# Review and customize the config
nano swoff.config.json

# Generate service worker + supporting files
npx @swoff/cli generate

The CLI creates:

Output	Description
`dist/sw-v{version}.js`	Versioned service worker
`dist/version.json`	Version manifest for update detection
`swoff/`	Client helpers — injector, fetch wrapper, cache, PWA install, etc.
`public/manifest.json`	Web App Manifest (if `public/` exists and no existing manifest)

Files in swoff/ are generated based on features toggles in your config. Every file is yours to edit.

Complete 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
    },
    "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"
  }
}

Adding Features

Toggle a feature without editing JSON by hand:

npx @swoff/cli add mutation-queue
npx @swoff/cli add background-sync

Then regenerate:

npx @swoff/cli generate

Cleaning Up

Remove all Swoff traces:

npx @swoff/cli clean

Deletes swoff/, swoff.config.json, and dist/version.json.

Next Steps

Schema Reference — full field list

Getting Started with Configuration

Getting Started with Configuration

Quick Setup

Complete Config

Adding Features

Cleaning Up

Next Steps

On this page