Migration Guide

Gradually move from manual SW code to config-driven generation.

Create Config

npx @swoff/cli init

This creates swoff.config.json and the swoff/ directory. Or create config manually:

{
  "$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",
      "mode": "all",
      "clearRuntimeOnUpdate": false
    },
    "navigation": {
      "mode": "spa",
      "preload": true,
      "fallback": "/index.html"
    }
  },
  "features": {
    "versionedSw": true,
    "pwa": { "enabled": true, "preventDefaultInstall": false },
    "crossTabSync": true,
    "tagInvalidation": true,
    "clientRegistration": true,
    "mutationQueue": false,
    "backgroundSync": false,
    "auth": { "enabled": false, "type": "bearer", "refreshPath": "/api/refresh", "userEndpoint": "/api/me" },
    "indexeddb": { "enabled": false, "name": "app-db", "stores": [] }
  },
  "build": {
    "outputDir": "dist",
    "swFilename": "sw"
  }
}

Generate SW

npx @swoff/cli generate

Creates dist/sw-v{version}.js, dist/version.json, and swoff/ with supporting files.

Register

Replace your manual SW registration with the generated swoff/sw-injector.js:

import { initServiceWorker } from "./swoff/sw-injector.js";

initServiceWorker();

If you prefer a basic registration (no version checking):

if ("serviceWorker" in navigator) {
  navigator.serviceWorker.register("/sw.js");
}

Add Features Incrementally

{
  "features": {
    "mutationQueue": true,
    "crossTabSync": true,
    "tagInvalidation": true
  }
}

Run npx @swoff/cli generate after each change.

Custom Cache Strategies

{
  "serviceWorker": {
    "strategy": {
      "patterns": {
        "/api/*": "network-first",
        "/static/*": "cache-first",
        "/images/*": "stale-while-revalidate"
      }
    }
  }
}

Custom Code Mode

If you need full custom SW code:

{
  "enabled": false
}

Then write your own sw.js manually. The CLI still generates supporting files into swoff/.

Manual → Config Mapping

Manual	Config
`CACHE_NAME = 'my-app-v1.0.0'`	`version: "from-package"`
`caches.match()`	Handled by generator
`caches.put()`	Handled by generator
Manual version cleanup	`versionedSw: true`
Custom install prompt	`autoActivate: false` + `sw-update-available` event

Rollback

Set "enabled": false in config and restore your manual SW file.

Next Steps

Schema Reference — full field list

Migration Guide

On this page