Build PWAs People Keep: Offline, Passkeys, and Share Targets Without the Pain

If your web app only works when the network is perfect, it will never earn a home‑screen spot. Today’s Progressive Web Apps (PWAs) can install like native apps, run offline, accept shared content, and sign in with passkeys—all without an app store. But many attempts still stumble on slow startup, fragile caching, or permissions that annoy more than they help.

This guide shows a practical way to ship a PWA users actually keep. We’ll focus on the parts that matter: a reliable offline core, thoughtful authentication, respectful notifications, and a clean install experience that behaves well on iOS, Android, and desktop. The goal is simple: an app that feels dependable and lightweight, not a web page trapped in a frame.

What Makes a PWA Worth Installing

A PWA that stays installed delivers at least four things consistently:

Predictable launch: starts fast, even offline, with a stable URL structure and a tiny first paint.
Durable data: reads/writes locally first, syncs when it can, and never throws away user work.
Comfortable sign‑in: uses passkeys or friction‑free flows, restores sessions safely, and avoids surprise lockouts.
Just‑enough native feel: install prompt, app icon, shortcuts, share target, and only the permissions that pay off.

Everything else—fancy animations, deep OS hooks—comes after you’ve nailed these fundamentals.

Architecture That Holds Up

App Shell and Routing

The classic PWA pattern still works: serve an app shell HTML (small, critical CSS inline, minimal JS) and hydrate features progressively. Register a service worker to cache the shell and route navigations to it, then fetch content or API data as needed.

Service Worker Strategy

Precache the app shell and your most common routes with a revisioned manifest. Tools like Workbox can generate this automatically.
Use stale‑while‑revalidate for static assets (icons, CSS, vendor JS). Users get instant responses, and updates stream in silently.
For HTML document navigations, serve a cached shell but short‑circuit errors with a clear offline fallback page that preserves intent (“You tried to open /settings; we’ll resume when you’re back online”).
Log service worker lifecycle events to analytics so you can spot update loops or failed activations early.

Local‑First Data Without Headaches

Use IndexedDB for structured data and the Cache Storage API for responses. Wrap IndexedDB with a tiny helper library to avoid callback hell. A simple pattern keeps you out of trouble:

Write locally first, enqueue sync jobs, and reflect optimistic UI immediately.
Derive a sync status for each item (pending, synced, failed) and show it in the UI without nagging.
Deduplicate jobs and coalesce writes to cut server load and flakiness.
Handle conflicts with a last‑write‑wins default and a small, discoverable “Resolve” UI when it matters (titles, labels, hand‑authored text).

Background Sync and Fallbacks

When supported, Background Sync can flush your queue after connectivity returns. When it’s not, trigger a best‑effort flush on app resume, visibility change, or timed retry. Your app should never require the tab to stay open for minutes just to send saved drafts.

Authentication With Passkeys

Passkeys (WebAuthn) reduce lockouts and credential reuse. A practical flow:

First login: allow email link or passwordless code. Immediately offer “Create a passkey on this device” after success.
Return login: prefer passkey; offer “Use a code instead” for recovery. Keep the CTA clear: “Sign in with device” beats jargon like “Platform authenticator.”
Session continuity: store short‑lived tokens and refresh silently. If a refresh fails, prompt gently without dumping the user out of context.
Cross‑device: mention that passkeys can sync via the OS keychain for most users, but still support recovery codes or email fallback for edge cases.

Tip: Keep your Relying Party ID stable (usually the top‑level domain) and test subdomain behavior carefully. A mismatch here is the fastest way to break sign‑in on only one platform at exactly the wrong time.

Capabilities That Feel Native

Respectful Notifications

Push can be great if you use it sparingly and tie every alert to clear user value. Best practices:

Ask permission only after demonstrating usefulness (“Notify me when my order is ready?”).
Group notifications per task, use concise titles, and include action buttons that open deep links you can handle offline.
Support silent updates for background data refresh where platforms allow it—don’t turn every change into a ping.
Give users a quick opt‑out in‑app. If they have to visit system settings, you’ve already lost them.

iOS note: Web push works for installed PWAs. Expect different permission flows and budgets; design your messaging to fit both iOS and Android gracefully.

Share Target and Web Share

Two small APIs make your PWA feel like part of the device:

Web Share: share text, links, and files out to other apps from your PWA.
Web Share Target: receive shared content from other apps into your PWA. Register a share target in your manifest, then route the POST to your service worker. Parse the payload, store it locally, and confirm success instantly.

Do not overcomplicate the first version. Accept a few MIME types you can handle well (text/plain, image/*, application/pdf), then grow as you learn how people actually use it.

File and Clipboard Access

Where supported, the File System Access API lets users edit local files without constant re‑prompts. Offer it as an advanced option and keep a copy‑in, copy‑out fallback for other platforms. Clipboard access is handy for power users; again, prompt judiciously and provide a manual paste field.

Shortcuts, Badging, and Theming

Small touches add up:

App shortcuts in the manifest jump users into frequent tasks (New note, Scan receipt, Start timer).
Badging can show a count without a full notification. Keep badges meaningful and low noise.
Theme color, splash, and maskable icons ensure a polished install experience. Test light/dark modes and high‑contrast themes.

Performance That Wins the Home Screen

Boot Speed Is the First Impression

Load time is your install pitch. On a cold start, most users will give you about a second. Hit it by:

Inlining critical CSS and deferring non‑critical styles.
Code splitting and lazy‑hydrating only what’s visible. Avoid loading heavy editors or charts until needed.
Using import maps or a lean module loader. Don’t stack bundlers until you know why.
Optimizing images (responsive sizes, modern formats like AVIF/WebP) and setting a sensible cache-control.
Shipping only one weight of your primary font and using system fonts for the rest. Serve fonts with a short preconnect and font-display: swap.

Measure What Matters

Track Core Web Vitals and a few app‑specific metrics:

First Contentful Paint (FCP) and Interaction to Next Paint (INP) for startup and input responsiveness.
CLS to prevent layout jump scares.
Time to Interactive UI: when the first tap reliably opens a route or modal.
Offline ready signal: the moment the app shell and key routes are cached and stable.

Use the Performance API to log milestones, not just averages. Averages hide the timeouts that drive uninstalls.

iOS, Android, and Desktop Gotchas

iOS Considerations

Install: ensure your manifest includes name, icons with maskable purpose, and a theme color. iOS is more sensitive to icon shapes.
Service workers: supported; test cache size expectations and eviction behavior. Keep the precache tight.
Push: available for installed PWAs; request permission after a user gesture and value preview.
Share target: check current support; offer mailto: or upload UI as fallback when needed.

Android Highlights

Install prompts: Chrome’s install criteria are clear; hit them and you’ll see a clean path to “Add to Home screen.”
File System Access and Web Share/Target: typically stronger coverage; still offer fallbacks for non‑Chromium browsers.
TWA (Trusted Web Activity): later, if you want a Play listing, a TWA can wrap your PWA without a heavy native shell. Not required for a great web install.

Desktop Nuances

Install UI: most modern browsers show a small plus button or menu option. Add an in‑app “Install” cue for discoverability.
Window controls: consider titlebar areas and drag regions so your app looks native.
File handlers: on desktop, registering file types works well; test double‑click flows across browsers.

Ship It Safely

Security Basics You Can’t Skip

HTTPS everywhere, including APIs and asset CDNs. Use HSTS.
Content Security Policy with no wildcards in script-src. Consider Subresource Integrity for third‑party scripts.
Permission hygiene: treat notifications, file system access, and camera/mic as optional accelerators, not prerequisites.

Updates Without User Pain

Service workers can get stuck if you’re careless. A simple, safe approach:

Version your precache and avoid skipWaiting by default. Let the new worker take control on next launch to prevent mid‑session reloads.
Show a gentle “Update available” toast on activation; tapping it reloads.
Migrate IndexedDB with additive schemas. Keep a last good backup in a side store to undo mistakes.
If an update fails repeatedly, expose a debug tool in Settings: “Reset cached data (keeps your content).”

Accessibility and Inclusivity

Use semantic HTML and ARIA only where necessary. Test with screen readers.
Honor prefers-reduced-motion and prefers-color-scheme. Provide high‑contrast themes.
Design offline/online transitions that are visible and polite—announce state changes to assistive tech.

Rollout Checklist

Manifest: name, short_name, start_url, scope, display standalone, theme/background colors, maskable icons, shortcuts, share target if needed.
Service worker: precache list, runtime caching, offline fallback routes, robust error handling.
Install flow: in‑app “Install” hint, iOS/Android/desktop tests, proper splash and icon treatments.
Auth: passkey setup and sign‑in, recovery paths, token refresh, device logout UX.
Data: local‑first writes, sync queue, conflict UI, background sync or fallback.
Capabilities: notifications behind clear value, share target tested with files and text, file access fallback.
Performance: FCP under 1s on mid‑range mobile, INP targets met, images sized, code split verified.
Safety: CSP, integrity, HTTPS, permission audits, privacy policy linked in settings.

Analytics Without Creep

Measure success without tracking people around the web. Focus on product health:

Install attempts (in‑app prompt clicks) and completions (app launched via standalone display mode).
Offline session count and duration, queue size, sync success rate, and time to “fully offline ready.”
Passkey enroll and success rates, plus recovery path use.
Notification opt‑ins, delivery, and action button rates; opt‑outs per screen to find noisy spots.

Aggregate, anonymize, and sample. You don’t need cross‑app identifiers for any of this.

Maintaining Delight Over Time

Feature Flags and Progressive Enhancements

Introduce new capabilities behind small, reversible flags. Detect APIs at runtime and surface the best experience available on that device. If File System Access isn’t there, present a clean upload/download flow. Users will appreciate reliability over parity.

Keep the Cache Humble

Precache only what’s necessary to boot fast offline. Everything else should be evictable. Periodically surface a background task that trims old caches and databases. Users don’t want a 500 MB web app.

Design for the Next Launch

Home‑screen presence changes behavior. People expect fast resume, deep links that never break, and state that survives connectivity dips. If you treat every open like a fresh page view, churn will creep in. Instead, restore context, keep a crisp back stack, and surface “Take me where I left off” as a first‑class entry point.

Example Implementation Sketch

Minimal Service Worker Layout

Without code, here’s the mental model:

install: open a versioned precache, add shell assets, and warm key routes.
activate: clean old caches, migrate small bits if needed.
fetch:
- HTML navigations → respond with cached shell; fetch content in parallel and update the store.
- Static assets → stale‑while‑revalidate.
- API calls → network‑first with timeout; if offline, serve from local store or return a synthetic “queued” response.
sync: flush write queue; mark items synced; notify UI.
push: update local store, set a badge, and optionally show a notification with deep link actions.

Data Model Hints

Every record: id, updatedAt, syncState, and a mutationVersion to resolve conflicts.
Keep an Outbox store with dedup keys (type:id) and a small payload. Server expands as needed.
Schedule retries with exponential backoff and a cap; respect metered connections when detectable.

Common Failure Modes (and Simple Fixes)

Users see blank screens after updates: You forced skipWaiting and reloaded mid‑session. Default to a gentle “Refresh to update” banner.
Offline opens show old UI: You precached too much. Trim to shell; fetch content after paint with loading states.
Passkey enroll works but sign‑in fails on subdomain: RP ID mismatch. Consolidate auth on the apex domain or set a stable RP ID.
Push feels spammy: You asked too early and too often. Gate on intent (order status switch, follow author, price alert).
Cache grows unbounded: Versioned precache without cleanup. Delete all caches not in a whitelist during activate.

Team Playbook: Who Owns What

Product

Define when the app must work offline and which tasks get notifications or badges.
Set install success criteria and require performance budgets in the roadmap.

Engineering

Build a test matrix for iOS, Android, and desktop browsers; automate install and offline tests where possible.
Instrument service worker lifecycle and sync health; pageviews alone won’t catch the real problems.

Design

Craft clear, low‑friction permission prompts with value copy and the option to say “Not now.”
Own the offline states, error messages, and recovery UIs; these are part of the brand too.

When to Add a Store Listing

A strong PWA often stands alone. Add a store listing if you need:

Discovery from store search in your category.
Specific OS hooks gated behind store policies.
Enterprise distribution requirements (managed devices, kiosk modes) or a TWA wrap for Android.

Otherwise, the best path is still the simplest: a great web install, a link people can share, and a small footprint that updates instantly.

Summary:

Build a tight app shell with a predictable offline route and measured caching.
Go local‑first for data, queue writes, and resolve conflicts in the UI.
Passkeys make sign‑in fast and safe; keep humane recovery options.
Add native‑feeling touches—share target, shortcuts, badging—only where they add value.
Hit performance budgets: sub‑1s FCP on mid‑range devices, low INP, controlled CLS.
Respect permissions, ship with a solid CSP, and update service workers gently.
Measure product health, not people, and maintain a humble cache.