"/home/yossef/notes/git/projects/maplibra/modules/Service Worker and Offline.md"

path: maplibra/modules/Service Worker and Offline.md

- **fileName**: Service Worker and Offline
- **Created on**: 2026-06-16 00:48:42

Service Worker and Offline

Purpose: App-side service worker registration, public worker file, and offline manifest.

Related: ../Home.md, ./Android Bridge.md, ./Offline Basemaps and PMTiles.md, ../risks/Offline Packaging Risks.md

Migrated from: obs_vault

What It Does

The app registers a service worker in production to cache assets for offline use. The service worker uses an offline-assets.json manifest to pre-cache essential files.

Service Worker Registration

src/app/service-worker.js handles registration:

• Registered only in production (disabled in dev via !isDev check)
• Registered via scheduleIdleTask to avoid blocking startup
• Supports unregistration when clearing cached maps

Public Service Worker

public/sw.js (the actual service worker file):

• Listens for install event to pre-cache assets
• Uses offline-assets.json manifest for the cache list
• Strategy: cache-first for static assets, network-first for API calls

Offline Manifest

offline-assets.json lists all assets that should be pre-cached:

• Must be kept in sync with the build output
• Drift between the manifest and actual build files causes offline failures

Important Files

• src/app/service-worker.js — Registration helper
• public/sw.js — Service worker implementation
• offline-assets.json or similar manifest — Pre-cache list

How It Connects

• bootstrapShell registers the service worker during startup

• Settings menu "Download offline data" triggers prefetch via requestOfflinePrefetch()

• "Clear cached maps" unregisters the service worker and clears caches

• Android bridge may trigger offline prefetching for packaged maps

  continue:[[]]
  before:[[]]