How to Build a Progressive Web App That Fails Safely

Define the offline and recovery contract first

A PWA should degrade into an understandable website, not a mystery copy of the server. Name the minimum useful offline result, which records remain authoritative on the server, and what the user sees when local storage, permission, or synchronization is unavailable.

• One HTTPS web workflow that already works online: Choose a bounded path such as reading assigned tasks and drafting one update. It must already handle loading, empty, invalid, denied, stale, and failed states over a normal network before a service worker can improve it.
• An offline capability statement: Write whether the first release offers only a branded offline page, cached read-only records, or queued writes. List which routes, assets, records, and actions are included and which actions explicitly require a connection.
• A browser and device matrix: Choose real Chrome or Edge, Safari, and Firefox versions that match the audience. Treat desktop, Android, iOS, and iPadOS as separate install and permission environments instead of assuming one browser name behaves identically everywhere.
• Server-side idempotency and conflict rules: Before queuing writes, define a stable operation ID, authenticated user and tenant, server deduplication, expected record version, conflict response, retention, and the safe action when a queued operation can no longer be accepted.
• Storage-loss and update recovery owners: Decide which local data can be rebuilt, which unsent drafts need export or warning, who can pause a rollout, how old and new app versions coexist, and when to clear one cache versus unregistering the worker as an incident action.

How much offline behavior should the first PWA own?

Offline depth is a product and data-consistency decision. Each layer adds value, but it also adds cache invalidation, storage, conflict, privacy, update, and recovery work. Pick the smallest layer that supports the real interruption your users face.

Recommended:Start with an offline fallback, then add read-only records if they solve a measured interruption. Add queued writes only when the workflow cannot wait for connectivity and the server already supports idempotency and version conflicts. A manifest and install icon do not justify accepting offline writes.

Build a progressive web app in 10 operational steps

Layer install metadata, offline behavior, local data, updates, tests, and operations onto one reliable HTTPS web workflow.

{
  "id": "/tasks/",
  "name": "Field Tasks",
  "short_name": "Tasks",
  "start_url": "/tasks/",
  "scope": "/tasks/",
  "display": "standalone",
  "background_color": "#fffaf5",
  "theme_color": "#f97316",
  "icons": [
    { "src": "/icons/task-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/task-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

export async function registerServiceWorker() {
  if (!('serviceWorker' in navigator)) return { supported: false }

  try {
    const registration = await navigator.serviceWorker.register('/sw.js', {
      scope: '/',
      updateViaCache: 'none',
    })
    return { supported: true, scope: registration.scope }
  } catch (error) {
    console.error('Service worker registration failed', {
      release: '2026.07.19.1',
      error: error instanceof Error ? error.name : 'UnknownError',
    })
    return { supported: true, scope: null }
  }
}

const CACHE = 'field-tasks-shell-v1'
const OFFLINE_URL = '/offline.html'
const SHELL = [OFFLINE_URL, '/assets/app.v1.css', '/assets/app.v1.js']

self.addEventListener('install', (event) => {
  event.waitUntil(caches.open(CACHE).then((cache) => cache.addAll(SHELL)))
})

self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((keys) =>
      Promise.all(keys.filter((key) => key.startsWith('field-tasks-') && key !== CACHE)
        .map((key) => caches.delete(key))),
    ),
  )
})

self.addEventListener('fetch', (event) => {
  const request = event.request
  const url = new URL(request.url)
  if (request.method !== 'GET' || url.origin !== location.origin) return

  if (request.mode === 'navigate') {
    event.respondWith(fetch(request).catch(() => caches.match(OFFLINE_URL)))
  }
})

type OutboxOperation = {
  id: string
  accountId: string
  tenantId: string
  kind: 'complete_task'
  recordId: string
  expectedVersion: number
  payload: { completedAt: string }
  state: 'pending' | 'sending' | 'failed' | 'conflicted'
  attempts: number
  nextAttemptAt: string
  createdAt: string
}

// Persist this row in one IndexedDB transaction before the UI says “queued”.
// Reuse id as the server idempotency key for every retry of this logical action.

What the result can look like

The minimum PWA release matrix

A PWA crosses page, worker, local storage, server, browser, operating-system, and sometimes push-service boundaries. Each test should name the device and browser version, app and worker release, starting storage, actor, action, and expected visible and server state.

Common PWA failures and how to diagnose them

Start with the browser and OS version, public origin, manifest URL, worker script and scope, app and worker release, controller state, cache version, account, operation ID, permission, and bounded server result. Do not begin by clearing all storage or dumping private data into logs.

Deploy and operate the PWA as a versioned distributed client

Deploy

Publish over trusted HTTPS with a stable worker URL, content-addressed immutable assets, valid manifest and icon responses, bounded worker scope, backward-compatible server endpoints, and a documented previous release and recovery point.

Roll out by app and worker release cohort. Keep old and new cache and data schema expectations compatible until controlled clients have upgraded; do not force activation merely to make a release dashboard look current.

Run public-origin install, launch, offline, reconnect, update, and optional push smoke tests on the real devices named in the support matrix before opening wider traffic.

Monitor

Track worker registration, install, waiting, activation, and controller failures by browser, OS, app release, and worker release without full URLs, cached payloads, tokens, or user content.

Track offline fallback use, IndexedDB and quota failures, outbox depth and age, retries, idempotency duplicates, conflicts, reconciliation, permission outcomes, subscription churn, push response classes, and notification clicks.

Separate server acceptance from user outcome: a queued outbox request is not saved, a push-service 201 or 202 is not displayed, an install event is not retention, and persistent-storage approval is not a backup.

Recover

For an unsafe release, pause promotion, keep backward-compatible APIs, restore the previous app assets, and let the normal worker lifecycle move clients back. Rehearse cache and IndexedDB migrations in both directions before relying on whole-origin deletion.

Use cache cleanup only for cache-owned artifacts. Preserve or export unsent drafts and outbox rows when safe; never unregister the worker and clear all origin storage as a first response to an update bug.

If local data is lost or evicted, resynchronize authoritative records from the server, mark unrecoverable drafts plainly, reconcile pending operation IDs, and prevent a stale client from silently replaying work under another account.

Security and privacy boundaries for an installed web client

A service worker can intercept origin requests, local storage can outlive a session, an installed window can look more trusted than a tab, and push subscriptions are sensitive capability URLs. Treat the PWA layer as privileged application code, not a cosmetic wrapper.

• Serve app, manifest, worker, icons, APIs, and push registration over HTTPS. Protect the source and deployment path for the stable worker URL, use a restrictive Content Security Policy where compatible, and review every route it controls.
• Do not cache personalized HTML, authorization responses, secrets, raw tokens, cross-tenant data, or private API bodies with a shared rule. Scope local records and outbox rows to the authenticated account and clear or lock them on logout according to the documented offline-access policy.
• Authorize every replayed operation on the server, bind it to the intended tenant, validate its payload again, enforce idempotency and version preconditions, and reject an operation that belongs to a prior session or revoked account.
• Treat push subscription endpoints and keys as sensitive. Require authenticated and CSRF-safe create and delete routes, store only what sending needs, never place subscriptions in analytics or URLs, and remove endpoints that return terminal errors.
• Request notification permission only from a clear user action and explain the event class. Push must produce a visible user-controlled notification where required, and the primary workflow must not depend on notification delivery.
• Assume Cache and IndexedDB can be inspected on a possessed device and can be evicted. Minimize local personal data, define retention and deletion, encrypt especially sensitive application payloads when the threat model requires it, and keep server-side revocation effective.

Progressive web app FAQ