ali-ahnaf / ali-ahnaf/pocket_pixel
Offline support: service worker, local caching, and sync on reconnect (Frontend)
- Ngôn ngữ chính
- TypeScript
- Star
- 14
- Fork
- 91
- Chỉ số merge pull request
- Không có pull request nào được merge trong 30 ngày
Mô tả
## 📡 Context / Background
Pocket Pixel is a web app that currently requires an active internet connection to function. If a user loses connectivity, they see errors or blank screens. Adding **offline support** means the app continues to work (read, and ideally write) without a network, and then **syncs changes automatically** when the connection is restored.
> **This is part of an epic.** This issue covers the frontend (service worker, local storage, sync UI). The backend issue covers the sync API endpoint.
---
## 🐛 Problem / Goal
The app has no offline capability. Users who lose network access cannot view their data or queue new transactions. We want to:
1. Serve the app shell from cache so it loads without a network
2. Cache API responses (transactions, vaults, debts, etc.) for offline reading
3. Queue write operations (new transactions, etc.) when offline and replay them when back online
4. Show the user clear feedback about offline/online status and sync progress
---
## 🛠️ Suggested Approach
The UI is a Next.js 14 app in `packages/ui/`. Here is a recommended approach:
### 1. Register a Service Worker
Next.js supports custom service workers. Use the [`next-pwa`](https://github.com/DucanNG/next-pwa) package or write a custom service worker in `packages/ui/public/sw.js`. The service worker should:
- Cache the app shell (HTML, JS, CSS) on install
- Intercept `fetch` calls and serve cached API responses when offline
### 2. Cache API responses
Use the **Cache Storage API** or **IndexedDB** (via a library like `idb`) to cache GET responses from the API. On each successful fetch, update the cache. On failure (no network), return the cached version.
### 3. Queue offline writes with a Background Sync queue
When a write (POST/PATCH/DELETE) fails due to being offline:
- Save the request details (URL, method, body) to IndexedDB
- Register a **Background Sync** event (or a manual retry on reconnect) to replay queued requests
### 4. Detect online/offline state and notify the user
Use the browser's `navigator.onLine` and `window` `online`/`offline` events:
```ts
window.addEventListener('online', () => { /* trigger sync, show banner */ });
window.addEventListener('offline', () => { /* show offline banner */ });
```
Show a small banner or toast when the user goes offline, and another when they come back online and sync completes.
### 5. Files to look at / create
```
packages/ui/public/sw.js ← new service worker file
packages/ui/src/app/layout.tsx ← register the service worker here
packages/ui/src/components/ ← add an OfflineBanner component
packages/ui/src/lib/api/ ← wrap API calls to handle offline queuing
```
---
## ✅ Acceptance Criteria
- [ ] The app shell loads correctly with no network (after first visit)
- [ ] Previously fetched data (transactions, vaults, debts) is readable when offline
- [ ] New transactions created while offline are queued and synced when back online
- [ ] A visible indicator informs the user they are offline
- [ ] When the connection is restored, queued operations sync automatically and the UI updates
- [ ] No regressions in online functionality
Hướng dẫn đóng góp
Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này
Đánh giá
Issue này chưa được đánh giá.