Progressive
web app development
in Long Beach

A service worker sits between the page and the network. Every request the app makes passes through it, and the worker decides where the answer comes from. That decision is the caching strategy. Most confusion about PWAs starts here, because a single strategy applied to everything produces strange bugs.

There are five basic patterns. Cache first answers from the local cache and goes to the network only when nothing is stored. Network first tries the server and falls back to the cache when the request fails. Stale while revalidate returns the cached copy at once and quietly fetches a fresh one for next time. Network only and cache only do exactly what their names say. Libraries such as Workbox ship all five as ready building blocks.

The skill lies in matching a pattern to each kind of request. Start by sorting the traffic of the app into groups. Static files with a content hash in the name, like app.3f9a.js, never change under the same address. Cache first suits them perfectly. Once stored, they can be served from disk for as long as that version lives.

HTML navigations behave differently. The page shell may be generic, but the content inside often changes. Network first with a short timeout works well here. If the server does not answer within a few seconds, the worker serves the last stored copy or a dedicated offline page. A user on a weak signal sees something instead of a spinning browser tab.

Images are a third group. They are heavy and rarely change once published. Cache first with an expiry rule keeps the gallery fast without filling the disk forever. A limit on the number of entries matters just as much as an age limit. Without it, a catalog app slowly hoards every product photo a user has ever scrolled past.

API responses need the most thought. Reference data, such as a list of categories or store opening hours, fits stale while revalidate. A slightly old answer is fine, and the fresh one arrives a moment later. Prices, stock levels and account balances are another story. Showing the figure from yesterday there creates real problems, so network first or network only is safer.

Some requests should never touch the cache. POST, PUT and DELETE calls change data on the server. Cache Storage does not accept them anyway, but a careless catch-all handler can still swallow their errors. Let them go straight to the network. Handle failure in the app code, where the interface can explain what happened.

Third-party files deserve a warning. A script or font loaded from another domain without CORS headers returns an opaque response. The worker cannot read its status code. Browsers also count such responses against storage as if they were large, sometimes several megabytes each. Caching many of them can burn through the quota quickly. Where possible, self-host fonts and critical scripts.

Audio and video need a special case. Media players request byte ranges instead of whole files. A plain cached response ignores the range header, and playback stalls or jumps in odd ways. Either leave media to the network or add a range-aware handler. Few apps truly need offline video. Ask before building it.

A practical way to document all this is a small routing table. One column lists the request pattern, the next names the strategy, then the expiry and the size limit. Developers keep it next to the worker code. Testers use it to check behaviour with the network switched off.

Timeouts belong in the same table. A network first rule without a timeout can hang for a long time on a connection that is technically alive but barely moving. That half-connected state is common on trains and in lifts. Three or four seconds is a reasonable starting point for page requests, then adjust after watching real sessions.

Revisit the table whenever a new feature adds a new kind of request. A search endpoint, a map tile server or a video stream each need their own row. Guessing later, after a user reports stale data, costs far more time than a single line written on day one.

The manifest is a small JSON file linked from every page with a link tag. It tells the browser what the installed app is called, which icon to show and how the window should look. It takes an hour to write. It takes much longer to fix once thousands of people have installed an app with the wrong values.

Start with identity. The id field names the app for the browser. If it is missing, the browser falls back to start_url, and that creates a trap. Change the start address later, perhaps to add a tracking parameter, and some browsers treat the result as a different application. Set id once, early, and never touch it again.

The name and short_name fields look trivial. They are not. Name appears in install dialogs and app switchers, where there is room for a few words. Short_name sits under the icon on a home screen, and anything longer than about twelve characters gets cut. Write both deliberately. Do not let the second one become a truncated copy of the first.

Scope and start_url decide the borders of the app. Scope is the path prefix that counts as inside. A link outside it opens in a browser view or a separate tab. Setting scope to the root of a large marketing site can pull blog posts and help pages into the installed window, where they look out of place. A narrower scope, such as the path of the actual product, keeps the app focused.

Display controls the window. Standalone removes the address bar and looks like a native app. Minimal-ui keeps a thin strip with back and reload buttons on browsers that support it. Fullscreen suits games and kiosk screens. Browser means no install benefit at all. The newer display_override field lets you list preferences in order, with fallbacks for older engines.

Icons cause most of the visible defects. Provide at least a 192 pixel and a 512 pixel PNG. Add a maskable version too. Android crops icons into circles, squircles or rounded squares depending on the phone maker. A maskable icon keeps the logo inside a safe central zone, so the crop never slices through a letter. Tools that preview the mask shapes save guesswork.

Colours come next. Theme_color tints the status bar and the title bar on desktop. Background_color fills the splash screen that Android generates while the app starts. Pick a background that matches the first painted screen. A white splash followed by a dark interface produces a harsh flash on every launch.

Richer install dialogs are available on Chromium browsers. Add a description and a few screenshots, marked for narrow or wide form factors. The install sheet then looks closer to a store listing. The shortcuts field adds quick actions on a long press of the icon, for example new order or scan a code.

Apple devices read the manifest only in part. Safari still looks for an apple-touch-icon link for the home screen image, and it handles the splash screen in its own way. Keep those tags in the page head alongside the manifest.

The manifest also feeds the install prompt. On Chromium browsers, a valid file plus a registered service worker makes the app installable, and the page receives a beforeinstallprompt event. Store that event and offer installation at a sensible moment. After a second visit works. So does the screen that confirms a finished order. Showing the offer on the first screen mostly teaches people to dismiss it.

Finally, serve the file correctly. Use the application/manifest+json content type, keep it on the same origin as the app, and cache it with a short lifetime. Browsers check it for changes, but only when the file itself is reachable and fresh.

A PWA can keep a surprising amount of data on the device. Cache Storage holds responses, IndexedDB holds structured records and files, and the Origin Private File System offers fast file access for heavier work. The room is real. It is also borrowed, and the browser can take it back.

Each origin receives a quota. Its size depends on the browser and on free disk space, so there is no single number to design around. Chromium browsers allow an origin a large share of the disk. Firefox and Safari use their own formulas. The honest answer comes from the device itself. Calling navigator.storage.estimate returns how much the origin uses and how much is available right now.

Storage comes in two modes. By default it is best effort. When the device runs low on space, the browser may delete the data of origins that were used least recently, and it removes the whole origin at once, not single records. Persistent storage is protected from that automatic cleanup. An app requests it with navigator.storage.persist. Some browsers grant it silently for installed apps or for sites the user visits often. Others ask the user or simply decline.

Safari adds a rule of its own. For sites opened in the browser, script-writable storage can be wiped after a stretch of days without any user interaction with the site. Web apps added to the home screen are treated separately and keep their data on their own terms. This difference alone explains many reports that the app forgot everything.

Users clear data too. A tap on clear browsing data, a private window, a cleaning utility, a phone reset. None of these warn the app first. The design has to assume that local storage is a cache and the server holds the truth.

That principle leads to concrete rules. Anything the user typed and has not yet sent is the most valuable data on the device. Keep it in IndexedDB, not in memory, and show clearly that it is still waiting. Anything downloaded from the server can be fetched again. Losing it is an inconvenience, not a disaster.

Avoid localStorage for anything beyond tiny preferences. It is synchronous, so large reads block the main thread. It stores only strings. It is also unavailable inside a service worker, which makes it useless for offline logic.

Large files change the arithmetic. A field app that stores inspection photos or a media app that keeps downloaded lessons can reach the quota far sooner than a text app. Compress images on the device before saving them. Store one size, not three. Offer downloads per item rather than all at once, and let the user remove what they no longer need.

Write operations can fail. When the quota runs out, the browser throws a QuotaExceededError. Catch it. Remove old cache entries, drop expired records, and retry once. If space is still short, tell the user plainly what will not be available offline instead of failing in silence.

A settings screen helps. Show how much space the app uses, offer a button to clear downloaded content, and keep unsent items out of that button. People trust an app more when they can see and control what it keeps.

Test the ugly cases before launch. Fill the quota on purpose in developer tools. Clear site data in the middle of a session. Reopen the app after a week without use on an iPhone. Each scenario should end in a working app that simply downloads again.

A field technician fills in a report in a basement and presses send. There is no signal. What happens next decides whether people trust the app or go back to paper. The goal is simple to state: the report must leave the device later, exactly once, without the user babysitting it.

The Background Sync API was designed for this. The page stores the request, registers a sync with a tag, and the service worker receives a sync event when the browser believes the connection is back. The browser can fire that event even after the tab is closed. Workbox wraps the pattern in a plugin that queues failed requests and replays them.

The catch is support. Background Sync works in Chromium browsers. Safari and Firefox do not implement it. So every app needs a second path that does not depend on the API. Fortunately, that fallback is not complicated.

Put each outgoing item into an IndexedDB queue before any attempt to send it. Then try the network. On success, delete the item. On failure, leave it in place. Retry when the online event fires, when the app returns to the foreground and when it starts. Where Background Sync exists, register it as an extra trigger rather than the only one.

Duplicates are the next danger. A request may reach the server while the response gets lost on the way back. The device thinks it failed and sends again. Two identical orders appear. The cure is an idempotency key: a unique identifier generated on the device when the form is created and sent with every attempt. The server stores it and ignores repeats.

Authentication needs care as well. A queued item may wait for hours, and the access token can expire in the meantime. The replay code should refresh the token before sending and handle the case where the session has ended entirely. In that situation, keep the item, ask the user to sign in, then continue.

Conflicts deserve a policy. Suppose an offline edit changes a record that someone else updated in the office. The server can reject the stale version, accept the latest write or merge fields. There is no universal answer. Decide per data type, and make the server return a clear status the app can show.

Photos and attachments complicate the queue. Store them as Blobs in IndexedDB and upload them separately from the form fields. A large file on a slow link should not block a dozen small text reports waiting behind it.

Order sometimes matters. If a user creates a customer record and then an order for that customer, the order cannot reach the server first. Replay the queue in sequence for dependent items, and stop at the first failure instead of skipping ahead. Independent items, such as separate time sheets, can go in parallel.

The interface finishes the job. Each queued item needs a visible state: waiting, sending, sent or needs attention. A small counter on the main screen tells the user that three reports are still on the phone. Nobody should close the app believing the work reached the office when it did not.

Put a ceiling on the queue as well. An app that stays offline for days may pile up hundreds of items. Warn the user once the queue grows past a sensible size, and never delete an unsent item automatically. Losing data the person typed by hand is the one outcome the whole design exists to prevent.

Test the whole chain on a real device in airplane mode, then switch the connection back on and watch the queue drain.