CLI Reference

Swoff provides a command-line interface for easy project setup and management. The CLI helps you initialize, generate, validate, and manage Swoff in your projects.

Use npx to run the CLI without installation:

npx @swoff/cli init
npx @swoff/cli generate
npx @swoff/cli validate

Commands

init

Initialize Swoff in the current directory. Creates a swoff.config.json with sensible defaults and a swoff/ directory.

npx @swoff/cli init

Options:

--framework <name> - Explicitly set framework (auto-detected from package.json by default). Accepted values: react, vue, svelte, vanilla.

Examples:

# Basic initialization (auto-detects framework)
npx @swoff/cli init

# Explicitly set framework
npx @swoff/cli init --framework react

This command:

Creates swoff.config.json with default configuration
Creates swoff/ directory for generated files

Next steps after init:

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

# 2. Validate configuration
npx @swoff/cli validate

# 3. Generate all files
npx @swoff/cli generate

generate

Generate service worker and/or supporting files based on your configuration.

npx @swoff/cli generate

Options:

--sw-only - Generate only the service worker
--files-only - Generate only supporting files
--language <ts|js> - Force output language (auto-detected from project if omitted)

Examples:

# Generate both service worker and files
npx @swoff/cli generate

# Generate only service worker
npx @swoff/cli generate --sw-only

# Generate only supporting files
npx @swoff/cli generate --files-only

Generated files:

File	Feature Flag	Description
`swoff/sw-template.js`	always	SW template with placeholders
`swoff/sw-injector.js`	`clientRegistration`, `pwa`, `crossTabSync`	Client-side SW registration
`swoff/fetch-wrapper.js`	always	Fetch with cache strategy headers
`swoff/cache.js`	`tagInvalidation`	Tag-based cache invalidation
`swoff/invalidation-tags.js`	`tagInvalidation`	URL-to-tag generation helper
`swoff/store.js`	`mutationQueue`	IndexedDB CRUD operations
`swoff/reconcile.js`	`mutationQueue`	ID reconciliation after sync
`swoff/mutation-queue.js`	`mutationQueue`	Offline mutation queue
`swoff/background-sync.js`	`backgroundSync`	Background Sync API wrapper
`swoff/auth-store.js`	`auth`	Auth token storage (memory-only) + user/expiry persistence
`swoff/auth-fetch.js`	`auth`	Auth-aware fetch with `authenticatedFetch` + `withAuthHeaders`
`swoff/auth-user.js`	`auth`	Current user cache in IndexedDB
`swoff/auth-state.js`	`auth`	Auth state detection (authenticated/unauthenticated/loading)
`swoff/indexeddb.js`	`indexeddb`	DB setup with migrations
`swoff/pwa-install.js`	`pwa`	PWA install prompt handler
`swoff/sw-generator.js`	always	Build script for versioned SW
`swoff/swoff.d.ts`	always (TS projects)	TypeScript declarations
`public/manifest.json`	`pwa`	Web app manifest

After generation, integrate into your app:

// In your app entry point (e.g., main.tsx, app.js)
import { initServiceWorker } from "./swoff/sw-injector.js";

initServiceWorker();

validate

Validate your swoff.config.json against the schema.

npx @swoff/cli validate

What it checks:

Required fields are present (enabled, version, serviceWorker, features, build)
serviceWorker.autoRegister, autoActivate are booleans
serviceWorker.strategy.default is one of the 6 valid strategies
serviceWorker.strategy.mode is "all" or "explicit-only"
serviceWorker.navigation.mode is "spa" or "default"
serviceWorker.navigation.preload is a boolean
serviceWorker.navigation.fallback is a string
Feature flags are known and correct type (boolean or object)
Object features (pwa, auth, indexeddb) have valid sub-fields
pwa.enabled and preventDefaultInstall are booleans
auth has enabled (boolean), type ("cookie"/"bearer"/"custom"), refreshPath and userEndpoint (strings)
indexeddb has enabled (boolean), name (alphanumeric), stores (string array)
crossTabSync requires tagInvalidation to be enabled
backgroundSync requires mutationQueue to be enabled
version is "from-package" or valid semver
minSupportedVersion is valid semver
build.outputDir and swFilename are strings

Example output:

Validating swoff.config.json...
✅ Configuration is valid!

Config summary:
  Version: from-package
  Default strategy: cache-first
  Features enabled: versionedSw, pwa, crossTabSync, tagInvalidation, clientRegistration

add

Add a specific feature to your configuration and regenerate files.

npx @swoff/cli add <feature>

Available Features:

Feature	Aliases	Config Written
`mutation-queue`	`mutationqueue`	`{ "mutationQueue": true }`
`pwa`	—	`{ "pwa": { "enabled": true } }`
`cross-tab`	`crosstab`	`{ "crossTabSync": true, "tagInvalidation": true }`
`auth`	—	`{ "auth": { "enabled": true, "type": "bearer", "refreshPath": "/api/refresh", "userEndpoint": "/api/me" } }`
`tag-invalidation`	`taginvalidation`	`{ "tagInvalidation": true }`
`background-sync`	`backgroundsync`	`{ "backgroundSync": true }`
`indexeddb`	—	`{ "indexeddb": { "enabled": true } }`

Examples:

# Add mutation queue
npx @swoff/cli add mutation-queue

# Add PWA components
npx @swoff/cli add pwa

# Add tag-based cache invalidation
npx @swoff/cli add tag-invalidation

info

Display a summary of your current Swoff configuration and generated files.

npx @swoff/cli info

Example output:

Swoff Configuration Summary
===========================
Version: from-package
SW Version: (from package.json)
Default Strategy: cache-first
Auto Register: true
Auto Activate: false

Features Enabled:
  versionedSw
  pwa
  crossTabSync
  tagInvalidation
  clientRegistration

Generated Files:
  swoff/sw-template.js
  swoff/sw-injector.js
  swoff/fetch-wrapper.js
  swoff/cache.js
  swoff/pwa-install.js
  swoff/invalidation-tags.js
  swoff/sw-generator.js
  public/manifest.json

Service Worker: dist/sw-v1.0.0.js
Version Info: dist/version.json

clean

Remove all Swoff traces from the project — full uninstall.

npx @swoff/cli clean

Behavior:

Removes the swoff/ directory
Deletes swoff.config.json
Deletes dist/version.json

Example output:

Cleaning Swoff Files
====================
Removed: swoff/
Removed: swoff.config.json
Removed: dist/version.json
✅ Cleaned 3 files.

help

Show help information for commands.

# Show all commands
npx @swoff/cli help

# Show specific command help
npx @swoff/cli help init
npx @swoff/cli help generate
npx @swoff/cli help info

Common Workflows

New Project Setup

# 1. Initialize Swoff
npx @swoff/cli init --framework react

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

# 3. Validate configuration
npx @swoff/cli validate

# 4. Generate files
npx @swoff/cli generate

# 5. Check what was generated
npx @swoff/cli info

Incremental Feature Addition

# Start with basic setup
npx @swoff/cli init

# Add features one at a time
npx @swoff/cli add mutation-queue
npx @swoff/cli add pwa
npx @swoff/cli add tag-invalidation

# Generate after each change (or once at the end)
npx @swoff/cli generate

Configuration Iteration

# Edit your config
nano swoff.config.json

# Validate before generating
npx @swoff/cli validate

# Regenerate files
npx @swoff/cli generate

# Review what changed
npx @swoff/cli info

Cleanup / Uninstall

# Remove all Swoff traces
npx @swoff/cli clean

Configuration File

The CLI expects swoff.config.json (or swoff.config.js) in the current working directory. You can customize:

Service worker settings (autoRegister, autoActivate, strategies)
Feature toggles (PWA, mutation queue, etc.)
Build output directory and filename
PWA install behavior
IndexedDB database name and stores

See Configuration Guide for details.

Troubleshooting

Command not found

Always use npx to run the CLI:

npx @swoff/cli init
npx @swoff/cli generate

Make sure you're running from your project directory:

cd my-project
npx @swoff/cli init

Validation errors

Run npx @swoff/cli validate to see specific errors in your configuration:

npx @swoff/cli validate
# Shows: Missing required fields: serviceWorker

Generation fails

Check that your config is valid and the directories exist:

npx @swoff/cli validate && npx @swoff/cli generate

No files generated

Check that enabled is true in your config:

{
  "enabled": true
}

Script Integration

Add Swoff commands to your package.json:

{
  "scripts": {
    "swoff:init": "npx @swoff/cli init",
    "swoff:generate": "npx @swoff/cli generate",
    "swoff:validate": "npx @swoff/cli validate",
    "swoff:info": "npx @swoff/cli info",
    "swoff:clean": "npx @swoff/cli clean",
    "build": "npm run swoff:generate && your-build-command"
  }
}

Now you can run:

npm run swoff:init
npm run swoff:generate
npm run swoff:validate
npm run swoff:info
npm run swoff:clean

CLI Reference

On this page