Offline first

In this article I want to talk about an aspect of web development I don't see discussed that often: Offline first apps and more specifically the combination of PouchDB and CouchDB being used for this purpose.

First off all what is meant by offline first?

It means that your app can function independent of a network connection. All interactions are handled by the browser itself including data manipulation. Only while you have access to the network is the local data synced with the server.

Why would you need this in a world of ubiquitous mobile internet?

Well, even if there usually is a good mobile network there can always be instances when it is not available. In buildings maybe the network is obstructed. Or one of my favorite examples: Train rides in Germany. There are very often regions with no or very slow connection in between bigger cities.

On the other side, the server handling your requests could be over capacity causing delays in the response.

Also, you are not dependent on the latency of the network between you and the server. That means that the performance of the app is always consistent and in many cases faster. Although that depends on the speed of the device itself.

By utilizing the resources of the device you additionally reduce the load on your servers which mostly are just concerned with syncing data.

The downside

That being said, the offline first approach does not work for everything. Especially for any transactional applications like banking or trading. But even here it can serve a purpose by saving your last account balance to also see that offline, for example.

Why PouchDB?

From the official website https://pouchdb.com/:

PouchDB is an open-source JavaScript database inspired by Apache CouchDB that is designed to run well within the browser. PouchDB was created to help web developers build applications that work as well offline as they do online. It enables applications to store data locally while offline, then synchronize it with CouchDB and compatible servers when the application is back online, keeping the user's data in sync no matter where they next login.

Internally in the browser it uses IndexedDB which is designed to "store significant amounts of structured data, including files/blobs" (https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API).

You store JSON documents that have the _id attribute which serves as the key of the document. Another such attribute is _rev that keeps track of the version number of the document being handled internally by PouchDB. But every time you update the document the latest _rev value must be present otherwise you get a document update conflict. Other than that you can store any valid JSON data you want in these documents.

Advantages of PouchDB compared to using the browser APIs directly to store data

Since it works seamlessly with CouchDB it takes care of the task of syncing PouchDB documents with CouchDB by calling just one method. CouchDB is the server application that actually permanently stores all your documents so that they don't get lost when you delete your browser storage and to distribute these documents between different devices.

The syncing mechanism proved to be very reliable in my usage so far, having a back off algorithm that incrementally uses bigger intervals to check if you're online again after going offline.

PouchDB also provides you with a mechanism to subscribe to all the doc changes happening in the database. This makes it possible to use it as a light message bus notifying your frontend for example to update the view of a document.

Concrete usage scenario

A concrete example where PouchDB is being used to store the date is the https://bootstrpd.com application from KAPSLY. Here you can track your time and cash contributions that you made to a project. Especially time tracking is something that you want to have available all the time and not just when you have an internet connection. It is really annoying if you want to track something but you can't because of no network or too much latency.

All the metrics are also calculated and stored in the browser which allows you to have a super fast evaluation of the current distribution of the contributions of every user in the project.


This article gave you a short introduction into offline first apps, their advantages and their drawbacks. Hopefully this will help you in the decision-making of the development of your next app taking into account that it can also be created offline first.

If you want to learn more about PouchDB and how it works you can try out this getting started guide: https://pouchdb. com/getting-started.html

Leave a Comment