Swoff - Build Offline-First Web Apps

Official reference implementation — a budget management app demonstrating Swoff patterns.

Budget Manager App

Official Swoff Reference Implementation

A budget management app demonstrating Swoff patterns in a real application: offline reads, local data with IndexedDB, queued writes, and versioned service worker updates.

Live Demo

GitHub: github.com/iamsuudi/budget-manager
Stack: React 19 + TanStack Router + Vite + Tailwind CSS v4

What It Demonstrates

Client-Side Data Runtime

Swoff powers the client runtime that keeps the app alive regardless of network conditions:

All routes cached offline — Service Worker caches all static assets via versioned SW
Data in IndexedDB — All app data stored locally via IndexedDB
Queued writes — Mutations are queued and synced when connection returns
TanStack Router — File-based routing works offline
Versioned SW updates — Users control when to update

Versioned Service Worker

dist/
├── sw-v1.1.9.js      ← Versioned SW (from package.json)
└── version.json        ← Version manifest

Update flow:

App checks version.json on load
If new version, fires sw-update-available event
useSWUpdate hook shows UpdatePrompt component
User approves → new SW downloads → progress bar shows → reload

IndexedDB Storage

Database: budget-manager (version 7)

Object Stores:
├── user              (key: id)
├── wallets           (key: id, index: by-deleted)
├── expenseCategories (key: id, index: by-deleted)
├── salaryCategories  (key: id, index: by-deleted)
├── invoices          (key: id, index: by-date)
├── monthBudgets     (key: id, index: by-month)
├── todoCategories   (key: id, index: by-deleted)
├── todoTasks        (key: id, indexes: by-category, by-date)
└── notes             (key: id, index: by-deleted)

Features:

Soft deletes (recovery possible)
ID generation: ${Date.now()}-${Math.random().toString(36)}
Storage size tracking with navigator.storage.estimate()

Security

PIN protection
Biometric authentication (WebAuthn)
Lock screen on app resume

PWA Install

Manifest configured
Install prompt handled
Works as standalone app

Key Files to Study

Service Worker

File	Purpose
`src/sw-template.js`	SW template with cache placeholders
`generate-sw.js`	Build script - generates versioned SW
`src/main.tsx`	SW registration & update logic

Data Storage

File	Purpose
`src/lib/storage/db.ts`	Database schema & config
`src/lib/storage/invoices.ts`	Expense/income transactions
`src/lib/storage/budgets.ts`	Monthly budgets
`src/lib/storage/todos.ts`	Todo categories & tasks
`src/lib/storage/notes.ts`	Rich text notes

Hooks & Components

File	Purpose
`src/hooks/useSWUpdate.tsx`	Update state management
`src/components/UpdatePrompt.tsx`	Update UI dialog
`src/components/SWProgressBar.tsx`	Install progress bar

Architecture Diagram

┌──────────────────────────────────────────┐
│           Browser (Client)               │
│                                          │
│  ┌────────────┐      ┌──────────────┐  │
│  │ SW v1.1.9  │      │  React App   │  │
│  │ (Assets)   │      │  (TanStack)  │  │
│  └────────────┘      └──────────────┘  │
│       │                   │              │
│       ▼                   ▼              │
│  ┌────────────┐      ┌──────────────┐  │
│  │ Cache API  │      │  IndexedDB   │  │
│  │ (Assets)   │      │  (App Data)  │  │
│  └────────────┘      └──────────────┘  │
│                                          │
└──────────────────────────────────────────┘

How to Run

git clone https://github.com/iamsuudi/budget-manager.git
cd budget-manager
bun install
bun run dev

Build for production:

bun run build
# Output: dist/ with sw-v1.1.9.js + version.json

Swoff Patterns Used

Pattern	File in Budget Manager
SW Template	`src/sw-template.js`
Build Script	`generate-sw.js`
Client Registration	`src/main.tsx`
Update Hook	`src/hooks/useSWUpdate.tsx`
IndexedDB Schema	`src/lib/storage/db.ts`
ID Generation	`src/lib/storage/index.ts`

Next Steps

Patterns — build your own offline app
Concepts — understand the architecture

Budget Manager App

On this page