Vanilla JS (with Bundler)

Swoff works with vanilla JS projects that use a bundler like Vite, esbuild, webpack, or Bun. The CLI generates ESM modules you import in your app code. For projects without a bundler (Go, Laravel, Rails, Django, Flask, plain HTML/JS), see the No-Bundler guide.

Quick start

npm install --save-dev @swoff/cli
npx @swoff/cli init --framework vanilla
npx @swoff/cli generate

Config

{
  "framework": "vanilla",
  "build": {
    "swOutput": "dist",
  },
  "features": {
    "serviceWorker": {
      "navigation": {
        "mode": "spa",
        "preload": true,
        "fallback": "/index.html",
        "precacheRoutes": ["/", "/about", "/offline"]
      },
      "strategy": {
        "default": "cache-first",
        "patterns": {
          "/api/*": "network-first"
        }
      }
    }
  }
}

navigation.mode: "spa" — serve precached fallback for all routes (app shell pattern)
precacheRoutes — critical pages to cache at install time for offline access

Where to place generated files

The build.swoffPath setting controls where generated files land. Defaults to "swoff" (project root). No copy step needed.

Entry point

Import and call initServiceWorker in your app entry:

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

initServiceWorker();

For projects without a bundler, see the No-Bundler guide.

Build script

Add the generator to your build chain:

vite build && node swoff/sw/generator.mjs

The generator reads build.swOutput from config and writes the final SW there.

Auth

For sites without a backend, skip auth entirely. For sites with a simple cookie-based auth:

{
  "features": {
    "auth": {
      "enabled": true,
      "type": "cookie",
      "routePaths": ["/login", "/logout"]
    }
  }
}

Adapters