Back to Explore
GuideVibeFix editorialUpdated Nov 20, 2026

Don't Wait for the Signal: Adding Offline-First and PWA Ability to Your Vibe Project

Does your product still work when the connection drops? Manifest, service worker, and IndexedDB; four caching tiers; a 2.4MB cache budget; outbox sync and three conflict rules; fictional funnel 1000→620→410→260→180.

Real photo of a hiker in a red jacket sitting on rocks at a mountain peak, looking at a phone with a backpack beside him

Three sentences first, so you read the right article. First, this is not about real-time collaborative editing — the site already has “Stop Editing Past Each Other: Real-Time Collaborative Editing for Your Vibe Project”; if several people need to edit the same document at the same time and see each other's cursors, read that one. This article is about one person, with no connection, and whether your product still works. Second, this is not about wrapping your website as a native app and shipping it to an app store — that is a different road, with its own review and release process. This article is about making the web page itself open, remember, and sync when the network is gone: offline-first and progressive web apps. Third, this is not about live streaming — streaming needs a constant connection, the opposite problem. This article covers one thing only: giving your vibe project offline ability, so users can finish the core task where the signal is worst, and quietly sync when they are back online. The whole article uses one running fictional example to make the ideas concrete: the example product is “Trail Notes”, a practice app that lets hikers record routes, check in at peaks, and write a few lines about the walk; the example user is “A-Shan”, an ordinary office worker who likes hiking on weekends; the numbers, conversations, and scenes in the example are entirely fictional exercises to explain the ideas, not a real product or real events. The funnel numbers in the last section are also a fictional sample, used to do the arithmetic, not real data.

The moment the connection drops, users learn your product is a decoration

A-Shan set off at six on a Saturday morning to climb a small hill outside the city. At the foot of the hill the signal was full, and he opened Trail Notes, checked today's route, saved three trails other people had walked, and wrote one line: “Good weather today, walking slowly.” Halfway up, the signal dropped to one bar, and he wanted to open a saved route to check whether the next fork went left or right. The page spun for a long time and gave him nothing but a loading spinner. Ten minutes later the signal was gone completely, and when he tapped again the browser handed him a blank offline dinosaur page. In that moment he understood: this app only existed when there was a connection, and the moment he needed it most was exactly when there was none.

He did not uninstall it after he came down, and he did not write a bad review. He simply never opened it again. Many vibe projects die exactly like this: not because they lack features, but because their core scenario collides with network conditions. The author writes code at home on stable broadband and never tests with the connection off; users open the product on the subway, in elevators, in the mountains, in underground car parks, and in dead zones. Offline is not a nice extra selling point. It is the line that decides whether your product can be trusted in the real world. The first step in offline-first is not learning a technique. It is admitting one thing: the user's environment is far worse than your development environment, and your product should be designed for the worst network, not the best.

Offline-first is a plain idea: make sure the product works with no connection first, and only then think about how much better it can be with one. The order cannot be reversed. Many projects do it backwards: they polish the online experience to perfection, then remember to add an offline notice that says “You are offline, please check your network.” That sentence helps the user not at all — of course he knows he is offline. What he needs is the route he already downloaded, the note he already wrote, and a button that saves now and sends later. In an offline-first product, losing the connection should not change the face of the interface or throw up a full-screen error page. It should keep working as if nothing happened, with a quiet line in a corner that says “Saved locally, will sync when you are back online.”

Decide first: what must work offline, and what can wait

Not everything needs to work offline. Making every feature work without a connection is a goal that will drag you down. The right move is to draw a line first: on this side is the core flow, which must be completable with no connection; on the other side are the nice extras, which can appear when there is a connection and hide when there is not. There is only one test for the line: what are the one or two things the user most wants to do when there is no connection? For Trail Notes the answer is clear: look at a saved route, and record a check-in and a few words about the moment. Looking at other people's new posts, liking their routes, and downloading photos someone just uploaded can all wait.

A-Shan's product was later rebuilt along exactly that line. Saved routes and trail data were quietly stored locally whenever the user opened them with a connection. Notes and check-ins were written to a local database first, and the interface immediately showed “Saved”, while the entry waited in a queue in the background to be uploaded when the network came back. Like and comment buttons did not disappear offline. They greyed out and said “Will send when online”, and tapping one did not produce an error — it simply joined the queue. The user saw no error on the whole mountain, lost not a single sentence, and when he got home and connected to Wi-Fi, all three check-ins were already synced, with the sync time shown beside them. Users cannot explain what is good about that experience, but they open the app again next weekend.

The line is different for every product. For an expense tracker the core is recording one expense, and that must work offline. For a recipe app the core is reading the steps while cooking, and a recipe already opened must be readable offline. For a check-in app the core is the check-in itself, and that must work offline. The other way round, searching the whole site, pulling a live leaderboard, and paying online are things that depend on the network by nature — a decent notice while offline is enough, and there is no need to force them. Before you write code, write down your core flow in three lines, then ask yourself: which of these three breaks when the connection breaks? Fix that one first.

Three pieces: the manifest, the service worker, and the local database

The technical skeleton of offline-first has only three pieces, and all three are needed, but each has a job that should not be confused with the others. The first is the web app manifest, a JSON file that tells the browser your app's name, which icons to use, what colour to show while opening, and whether it opens full-screen or inside a browser frame. Without it, the browser does not know your web page can be “installed” on the home screen, and users have to open the browser and type the address every time. With it, users can keep your app on their phone like a real app and open it with one tap.

The second piece is the service worker. It is a script that runs behind the web page, intercepts the network requests the app makes, and decides which ones go straight to the network, which ones are answered from the local cache, and which ones are written down to be sent when the connection returns. It is the master switch for offline ability: without it, a lost connection means the browser can only show an error page; with it, the app can still pull the page and the data out of the cache. One thing to note is that a service worker only works over HTTPS — localhost is the exception during local development. That means if your vibe project still runs on a plain HTTP temporary address, you cannot even test offline behaviour until you sort out HTTPS.

The third piece is the local database, usually IndexedDB. It is the storehouse inside the browser that can actually hold data, with far more room than localStorage, and it can hold structured records: routes, notes, check-ins, and a queue of operations waiting to sync. localStorage is only suited to a few switches and short strings; stuffing route data, images, and hundreds of notes into it will cause trouble quickly. Remember the division of labour in one sentence: the cache holds things that look like files — pages, scripts, styles, and images — and the database holds things that look like records — content the user wrote and operations waiting to be done. Mixing the two up is the most common beginner mistake.

None of these three pieces needs to be written from scratch. Workbox is a set of tools maintained by the Chrome team, built exactly for writing the caching logic inside a service worker, with ready-made strategies you can pick up and use. MDN's progressive web app documentation covers the manifest, the install conditions, and the offline mechanisms in full. The Learn PWA course on web.dev walks through the same ground step by step. Your job is not to invent the wheel. It is to fit these three pieces together around your product's core flow, and then test them on a real phone with the connection switched off.

Four caching strategies: do not treat everything the same way

The easiest mistake inside a service worker is to use the same caching method for every request. The result is either users who always see old content, or users who get nothing at all offline. The right approach is four tiers, one strategy for each kind of resource. The first tier is the app shell — the HTML, CSS, and main JavaScript files — and it uses cache-first: take it from the cache first, and only go to the network when it is not there. That way the app at least opens when offline, with the interface complete. The second tier is the user's own data, such as saved routes and notes already written, and it uses network-first with the cache as a fallback: take the newest version when there is a connection, and fall back to the previous copy in the cache when the network fails. Users neither see badly out-of-date data nor end up empty-handed offline.

The third tier is things that change rarely and are large, such as route cover images and avatars, and it uses stale-while-revalidate: serve the cached copy at once, and quietly check the network in the background for a newer version, swapping it in so the next opening shows the new one. Users feel no waiting, and the content does not stay old forever. The fourth tier is things that must never be cached: login state, payment results, live ticket availability, and other people's private messages. These must go over the network every time, because caching them causes real harm — a user could see someone else's order, or believe a payment succeeded when it did not. Before setting a strategy for any resource, ask one question: how bad is it if this copy is out of date? If being out of date only means being slightly old, cache boldly. If being out of date misleads people or loses money, never cache it.

One more detail: the cache needs a version name and a limit. Every time you ship a new version, give the cache a new name, and let the new service worker delete the old cache when it activates. Otherwise users can stay on the old version forever, and a bug you fixed will never reach them. A-Shan stepped on this trap the first time: he fixed a typo on the route page, but his own phone still showed the old version, and it took him a long while to work out that the old cache had never been cleared. Since then every release has carried a version number, and the service worker deletes the old cache before taking over the page. Image caches need a limit too — keep, say, only the fifty most recently opened images, and delete the least recently used when the limit is passed. Otherwise your app will quietly eat the user's phone storage.

One cache budget table: offline storage is not free and unlimited

Offline storage is not unlimited. The browser gives every site a quota, and when it is exceeded the stored data can be cleared. When phone storage gets tight, the browser clears first the sites that have not been opened for a long time. So before you ship, do the arithmetic for your app and write a cache budget table. Trail Notes' budget table looks like this: the app shell HTML is 180KB, the main JavaScript is 420KB, styles and fonts are 160KB, the icon set is 240KB, route text data is 600KB, and route cover thumbnails are 800KB. Add the six items together: 180 plus 420 is 600, plus 160 is 760, plus 240 is 1000, plus 600 is 1600, plus 800 is 2400KB, which is 2.4MB. The table totals 2.4MB, and the team set its own cap at 5MB, leaving double the headroom for future features and routes the user saves later.

The point of the table is not the numbers themselves. It is that the table forces you to make trade-offs. Thumbnails at 800KB are the biggest item, so if you want to squeeze the budget down, the first move is to cache small thumbnails instead of the original images. Route text data at 600KB, at about 30KB per route, holds roughly 20 routes, and anything beyond that rotates by the most recently opened. Without the table, the cache quietly grows to ten megabytes or more, and when the user looks in the phone settings and sees your app taking hundreds of megabytes, yours is the first app to be deleted. The budget table belongs in your release checklist, and every time a new feature is added, look at how much budget is left first.

One more thing that is easy to miss: cached files and database records are two separate bills. The 2.4MB above is only the cache bill. The user's notes and the pending sync queue in the database are a separate bill. Notes are plain text, a few KB each, so hundreds of notes are only a few MB. Original photos are the real cost — one phone photo is three to five MB, and ten of them are tens of MB. That is why Trail Notes set one rule: photos taken offline are stored locally as thumbnails first, and the originals are only uploaded when there is Wi-Fi. Users can see in settings how much space is used locally, and clear already-synced originals with one tap. Giving the user that choice is far more decent than quietly filling up their phone.

Writing offline: save it first, then talk about syncing

Reading offline is relatively easy. Writing offline is the real test. A user with no connection writes a paragraph, changes a title, or deletes a record. Those actions cannot wait for the network. They must take effect locally at once, and sync reliably when the connection returns. The standard pattern is the outbox: every write first goes into the local database, and at the same time a record is appended to a pending sync queue, while the interface shows the result immediately. When the network returns, the service worker or the sync logic in the page sends the queued operations to the server one by one, in order, deleting each one that succeeds and keeping the ones that fail for another try.

The order of the queue matters. One of A-Shan's check-ins was created first, then a sentence was edited, then a photo was added. These three operations must sync in that order — if the edit reaches the server first while the creation is still on its way, the server receives a change to a record that does not exist yet and returns an error. Retries need a limit too. Do not retry forever. Wait a few seconds after one failure and try again; if it still fails after three tries, stop and tell the user “One record did not sync, tap to retry”, instead of silently burning the user's data and battery in the background. Users can accept one failure. What they cannot accept is not knowing they lost something.

Conflicts are the hardest part of syncing, and they deserve to be thought through on their own. The most common case is the same note edited on two devices: one sentence changed on the phone with no connection, and another sentence changed on the computer with a connection, and when they sync the server has to decide which sentence stays. There are three roads. The first is last-write-wins: simple and rough, and fine for check-ins and likes, where losing one is no great loss. The second is field-level merging: compare the title and the body separately, and keep whoever changed each field, which suits records with a clear structure. The third is to let the user choose: show both versions and let the user pick one or merge them by hand, which suits notes and diaries, where losing a single sentence hurts. Trail Notes chose the third road: on a conflict it never quietly overwrites, but shows a line under the note, and tapping it shows both versions to pick from or merge by hand. The rule can be simple, but it must be decided in advance and written into the product, not improvised after a conflict has already happened.

The install experience: do not beg users to install on their first visit

Being installable on the home screen is the most app-like part of a progressive web app, but the timing of the install prompt matters a great deal. The browser fires the install event when the conditions are met: there is a manifest, there is a service worker, there are icons, and the page is served over HTTPS. That does not mean you should throw a large banner at the user on their first visit shouting “Install our app”. On a first visit the user does not even know what your product does yet. Begging for an install at that moment only makes them tap close, and many browsers remember that refusal and will not offer the chance again for a long while.

The right move is to wait until the user has a reason to stay, and then ask. Trail Notes waits until the user has opened the app a second time and saved at least one route, and only then shows a small note at the bottom of the page: “Put Trail Notes on your home screen, and you can read routes on the mountain with no signal”, with an “Install” button and a “Not now” close. Those who tap install go through the browser's install flow, and those who close it are not bothered again for a month. The timing has a logic to it: saving a route means the user really needs the product, and a second visit means they are not just passing by. Install conversion is not built by the size of the pop-up. It is built by one well-timed nudge after the user has already felt the value.

One more reality to mention about Apple phones: Safari on iPhone supports progressive web apps differently from Android. Installation goes through the browser's share menu, and abilities such as push notifications have their own limits. If your product has many iPhone users, the core offline features still work, but do not assume the install flow is identical to Android. Before shipping, walk through the whole flow on a real iPhone: open it from Safari, add it to the home screen, open it with the connection off, write a note, restore the connection, and watch the sync. A flow that passes in a simulator does not always pass on a real phone, and one pass on a real phone is worth more than reading the documentation ten times.

One fictional funnel: five steps that show whether offline really works

Once offline features ship, how do you know they are actually useful? Install numbers alone are not enough — installed and never used is the same as not installed. The Trail Notes team measured it with a five-step funnel, and the numbers are a fictional sample used to show how the arithmetic works. Suppose there are 1,000 visits: 620 people open the app a second time within 7 days, which is 62.0%; of those 620, 410 install the app on their home screen, which is 66.1%; of those 410, 260 use an offline feature at least once, which is 63.4%; of those 260, 180 successfully sync content they wrote offline after the connection returns, which is 69.2%. Overall, out of 1,000 visits, 180 people complete the whole journey from visit to offline use to successful sync, an overall conversion rate of 18.0%. The losses add up too: 380 people leave after the first step, 210 after the second, 150 after the third, and 80 after the fourth, leaving 180 at the end — 380 plus 210 plus 150 plus 80 plus 180 is exactly 1,000.

When you read a funnel, look at which step loses the most people, not just the final total. If the second step loses the most, users installed the app but never opened it without a connection — perhaps they do not even know offline use is possible, and the interface should say the offline state plainly. If the fourth step loses the most, syncing keeps failing, and the problem is in the queue and retry logic, not in the marketing. When Trail Notes ran this funnel the first time, the worst drop was from the third step to the fourth: many people wrote things offline, but syncing failed, and the cause turned out to be original photos too large to finish on a weak connection before timing out. After the change to sync text first and photos only on Wi-Fi, the fourth step's rate rose at once. That is the value of the funnel: it does not tell you whether the product is good. It tells you which step to fix next week.

Trail Notes offline funnel (fictional sample): 1,000 visits to 180 successful syncs, 18.0% overall

A pre-launch checklist: test it with the connection off before you ship

Offline features are most afraid of the sentence “it works on my computer”. Before shipping, walk through this checklist on a real phone. First, open the browser developer tools, switch the network to offline, refresh the page, and check whether the app still opens and whether the core pages are all there. Second, walk through the core flow while offline — write a piece of content, change a title, leave and come back, and check whether the content is still there. Third, restore the connection and watch whether syncing happens on its own, and whether a failed sync produces a notice. Fourth, ship an update once and check whether the old cache was cleared and whether the user gets the new version. Fifth, pick up a phone that has not opened the app for a long while, and check whether the browser clears the storage, and whether the app re-downloads gracefully instead of failing outright after the clear.

There are a few common traps too. The first is letting the service worker cache itself: if your build process treats the service worker file as an ordinary cached resource, the new version may never install, so remember to fetch it over the network every time. The second is testing only on Wi-Fi: a weak connection is far more common than no connection at all, and a request that hangs for ages is more painful than one that fails at once, so give network requests a timeout and fall back to the cache when it expires. The third is hiding the offline state: if users do not know they are offline, they do not know why new content is not loading, so put a small offline marker in a corner of the interface that says plainly “Offline, saved locally”, and it will save most of the confusion. The fourth is testing on Android and never on iPhone, which was covered above and needs no repeating.

Start with one small offline loop

If you want to start now, do not build the whole set at once. Build one small offline loop first: pick one core flow, make it completable with no connection, and make it sync when the connection returns. The first offline loop in Trail Notes had only three things: saved routes could be read offline, a check-in could be written offline, and it synced automatically when the phone reached Wi-Fi at home. Just those three things took a weekend, and after they worked, the team slowly added the install prompt, image caching, and conflict handling. Offline-first is not a big project that must be finished in one go. It is an ability that can be added one small step at a time, and with every step, users trust you a little more when there is no connection.

Back to A-Shan one last time. The next time he climbed, there was no signal halfway up, and he opened Trail Notes, and the saved route was simply there, with the fork-to-the-left note clear as day. At the peak he wrote one line — “A sea of clouds, worth the early start” — and pressed save, and the interface said “Saved locally”. When he got home and connected to Wi-Fi, the line was already synced. He never wrote a good review for the app. He simply opened it every weekend. For a vibe project, that is the best return offline-first can give you: when the user needs you most, you are there.

Views 11Comments 0

Comments (0)

ME
0/1000
Loading comments...

Sources

Browse projectsPublish your project

Related articles

Real photo: a laptop, tablet, and phone on a wooden table showing the same green-leaf website, the phone view with navigation in one column, a potted plant nearby
Guide
Squashed on phones? Responsive layout and media queries, explained plainly

One page should stand up on a phone, a tablet, and a computer. This guide follows MDN's Responsive web design, Using media queries, and the viewport meta reference: fluid HTML, the viewport tag, fluid grids and max-width, images that never burst their container, media query syntax, breakpoints set by content, mobile first, responsive type, testing capability instead of width, and a pre-launch checklist.

Mobile AppsDesign ExperienceFrontend Engineering
Real photo: a bank of light gray metal filing cabinets with one drawer pulled open, revealing rows of hanging file folders inside
Guide
A real database inside the browser: IndexedDB local storage, explained plainly

localStorage only stores strings and has no indexes. IndexedDB is a real database in the browser: structured data, far larger capacity, indexes, and transactions. Following MDN's Using IndexedDB, IDBDatabase, and IDBObjectStore: the five-step routine, opening, upgrades, keys, indexes, transactions, add versus put, get, cursors, ranges, and multi-tab upgrades.

Tool TipsData WorkflowsFrontend Engineering
Real photo: hands typing on a MacBook Pro showing JavaScript code that changes HTML content, with a white mouse, papers, and binders on a white desk
Guide
Functions without the confusion: JavaScript functions, parameters, and arrow functions, explained plainly

You already call functions every day; this guide names what you have been doing. Following MDN's Functions, Arrow function expressions, and Rest parameters: declarations versus expressions, parameters and arguments, default values, rest parameters, spread syntax, return values, arrow function shorthand, the this trap, callbacks, and scope.

Tool TipsFrontend EngineeringAI Coding