CLI Reference

Full documentation for every @swoff/cli command and flag.

`init`

Creates swoff.config.json in your project root. Auto-detects:

Framework: checks for react, vue, svelte dependencies in package.json (falls back to "vanilla" if no package.json found)

swoff init
swoff init --framework react   # override auto-detection

Flag	Type	Description
`--framework`	`"react"` \| `"nextjs"` \| `"remix"` \| `"tanstack-start-react"` \| `"astro"` \| `"nuxt"` \| `"sveltekit"` \| `"vike"` \| `"vue"` \| `"svelte"` \| `"vanilla"` \| `"no-bundler"`	Override framework auto-detection

`generate`

Generates the service worker and all supporting files into swoff/.

swoff generate
swoff generate --language js

Flag	Description
`--language`	`"ts"` \| `"js"` — override language auto-detection; forces `.tsx`/`.ts` or `.jsx`/`.js` output

What is generated

All files land in swoff/. See API Reference for the full reference.

File	Condition	Purpose
`client-injector.{ts\|js}`	always	Single entry point — wires SW registration, PWA install, mutation queue, cross-tab sync
`config.{ts\|js}`	`serverPush.enabled`	Project configuration — API_BASE for server-push endpoint
`connectivity.{ts\|js}`	`features.connectivity.enabled`	Online/offline detection with HEAD heartbeat
`db.{ts\|js}`	auto-enabled when auth, mutation queue, or push notifications is enabled	IndexedDB database open/init helpers
`fetch/core.{ts\|js}`	`features.tagInvalidation.enabled`	Unified fetch with caching, auth, offline queue, auto-invalidation
`cache/invalidate.{ts\|js}`	`features.tagInvalidation.enabled`	`invalidateByTag()` / `invalidateByTags()`
`cache/tags.{ts\|js}`	`features.tagInvalidation.enabled`	Tag generation helpers from URL paths
`storage.{ts\|js}`	always	Storage estimation (`getStorageEstimate` / `formatBytes`)
`reset.{ts\|js}`	always	`resetSwoff()` — wipes caches, IndexedDB databases, localStorage, unregisters SW
`auth/adapter.{ts\|js}`	`auth.enabled`	Auth provider adapter — generated template (cookie, bearer, or custom)
`auth/store.{ts\|js}`	`auth.enabled`	Token/user persistence + cascading clearAuth + cross-tab sync
`auth/state.{ts\|js}`	`auth.enabled`	Online/offline × auth state detection (connectivity manager)
`auth/check.{ts\|js}`	`auth.enabled`	Custom auth failure response detection
`graphql/index.{ts\|js}`	`graphql.enabled`	GraphQL wrapper with body-hash caching
`mutation/queue.{ts\|js}`	`mutationQueue.enabled`	Offline write queue in IndexedDB
`mutation/state.{ts\|js}`	`mutationQueue.enabled`	Per-mutation status tracking
`mutation/sync.{ts\|js}`	`mutationQueue.backgroundSync`	Background Sync API registration
`push-notification/index.{ts\|js}`	`pushNotifications`	Push notification subscription management
`pwa/prompt.{ts\|js}`	`pwa.enabled`	Install prompt handling (`isInstallable`, `promptInstall`)
`server-push/client.{ts\|js}`	`serverPush.enabled`	SSE/WebSocket connection manager (runs in SW)
`sw/template.js`	always	Service worker source — runs in SW scope
`sw/injector.{ts\|js}`	always	SW registration logic
`sw/generator.mjs`	always	Build-time script — embeds asset hashes
`sw/version.{ts\|js}`	always	`SW_VERSION` constant — embedded in SW for display / debugging
`adapters/*.tsx`	React-based framework only	Framework adapters. Other frameworks use `window.addEventListener` (see Blueprint)
`swoff.d.ts`	TypeScript	TypeScript declarations

PWA assets

PWA assets (icons, favicons, splash screens) are generated by the external @swoff/assets package — see below.

`assets`

PWA assets (icons, splash screens, manifests) are generated by the external @swoff/assets package:

npx @swoff/assets --source ./logo.svg

Run npx @swoff/assets --help for all flags (--source, --no-splash, --theme-color, etc.).

Generated assets by default:

File	Description
`public/icon-64.png`	Small PWA icon (64×64)
`public/icon-192.png`	Standard PWA icon (192×192)
`public/icon-512.png`	Large PWA icon (512×512)
`public/maskable-icon-512.png`	Maskable PWA icon (512×512) with safe zone padding
`public/apple-touch-icon.png`	Apple touch icon (180×180)
`public/favicon.ico`	Multi-size favicon (16×16, 32×32, 48×48)
`public/og-image.png`	Open Graph / social sharing image (1200×630) with centered logo
`public/splash-*.png`	Apple splash screens (7 sizes for all iOS devices)

After generation, manually reference these assets in your app. Run swoff assets --help for a copy-paste guide with the exact <link> and <meta> tags for your HTML <head>.

`validate`

Validates swoff.config.json against the schema. Reports unknown fields, type mismatches, and structural errors.

swoff validate

`clean`

Removes generated Swoff files and config:

swoff clean
swoff clean --yes     # skip confirmation prompt

Flag	Description
`--yes` / `-y`	Skip confirmation prompt

This deletes:

swoff/ directory (all generated files)
swoff.config.json

`help [command]`

Shows help text for a specific command.

swoff help
swoff help init
swoff help generate

Build script integration

The SW generator (sw/generator.mjs) must run after every build to produce the final service worker file. Run it directly:

node swoff/sw/generator.mjs

For Node.js projects, add it to your package.json build script:

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

The generator:

Reads swoff.config.json for output dir and strategy config
Reads sw/template.js — the service worker source code
Collects all built assets from the output directory
Replaces placeholders ([[CACHE_NAME]], [[ASSETS_LIST]], [[AUTO_SKIP_WAITING]]) with actual values
Writes the final SW file to build.swOutput (e.g. dist/sw.js)

CLI Reference

On this page