js.stuartsm
moderate

Offline-First Reading List

Build a reading list that works offline, backed by IndexedDB and a service worker with a documented caching strategy.

Practices: Networking, storage, and workers, Browser application architecture

Scenario

Build a reading list: save an article’s title, URL, and a short note; mark items read/unread; filter by status. The app must remain fully usable with no network connection — including adding new items — and reconcile once connectivity returns.

Requirements

Core

  • Reading-list data (recall IndexedDB) persists across reloads and remains fully readable and writable with the network disabled entirely.
  • A registered service worker (recall Service Workers) serves the app shell (HTML/CSS/JS) from cache when offline, so the app itself loads with no network at all, not just its data.
  • Your chosen caching strategy (cache-first, network-first-with-fallback, or stale-while-revalidate) is explicitly documented — which strategy, for which resources, and why — not just implemented silently.
  • The UI clearly communicates offline status and pending/unsynced changes, rather than silently behaving as if everything is normal.
  • The app works with core functionality present even before any JavaScript enhancement runs (progressive enhancement, recall Browser Application Architecture) — at minimum, a no-JavaScript visitor sees a clear message rather than a blank page.

Conflict and error states

  • Define and document what happens if the same item is modified while offline on two different tabs/devices and both later attempt to sync — even a simple “last write wins, documented as such” is acceptable, as long as it’s a deliberate, stated decision rather than undefined behavior.
  • A failed sync attempt after reconnecting is visible to the user, not silently dropped.

Stretch

  • A manual “retry sync” control for a failed sync.
  • Export the reading list as JSON, and import it back.

Privacy notes

  • Document what’s stored (title, URL, note — presumably no third-party tracking) and where (purely client-side IndexedDB, never sent to a server unless the project adds one) in the project’s own README or an in-app note.

Suggested milestones

  1. Build the reading list with IndexedDB persistence, online only, no service worker yet.
  2. Add a service worker caching the app shell; confirm the app loads with the network disabled.
  3. Confirm reading-list reads/writes work fully offline (they should already, since IndexedDB is local — verify explicitly).
  4. Add offline-status UI and the conflict/error-state handling.
  5. Document the caching strategy and privacy notes.

Acceptance checks

  • With the network disabled in DevTools, reloading the app still loads the shell and shows previously saved items.
  • Adding a new item while offline, then reconnecting, results in that item being present exactly once (not duplicated, not lost).
  • The documented caching strategy accurately describes what the code actually does.
  • A screen-reader or no-JavaScript visit still communicates the app’s basic purpose, rather than a blank or broken page.