How can you tell if a web app is offline-first? Short answer: you can’t. A well designed offline-first app feels absolutely no different than a traditional app. All the magic happens behind the scenes. Instead of the traditional client-server model we’re all used to, offline-first apps take advantage of technologies built into your local browser so users can experience a seamless online to offline transition.

Since we’re talking specifically about web apps here, we need a way to store data locally in the browser. The 3 main options you have are:

1. LocalStorage — around 5MB limit, can only store strings
2. WebSQL — deprecated
3. IndexedDB (IDB) — pretty much your only choice for document storage

If we don’t sound particularly enthusiastic about IDB, it’s because not many people are.

“IndexedDB API is powerful, but may seem too complicated for simple cases.” — MDN

That’s right. This quote was taken directly off the MDN website. They incidentally admit that IDB is a pain to work with, and boy is that true. Asynchronous JavaScript already gives people headaches and along with IDB being event-driven, it takes about 30 lines of tedious code just to insert your first piece of data.

Introducing turtleDB

The left shows what typical native IDB code may look like to insert “Bob” into the database. turtleDB can do this in 1 line (right).

We really believe that the complexity of IDB is a big detriment to the offline-first world. This was one of the driving factors behind us building turtleDB. We want developers to have the ability to create offline-first applications without learning all the quirks of IDB. Because of this, we decided to wrap IDB in a promise-based API (turtle-db.github.io/api) that feels more natural to work with and developers can invoke CRUD operations with just 1 line.

So now that we can perform CRUD queries in our browser, who would even use them?

Our target

We took some examples of common web apps and placed them in categories on a according to how easy or difficult it would be to convert them to an offline-first model. In the “Easy” category, we’re dealing with apps that don’t have a need for data storage of any kind. All they would need to work offline is some basic static asset caching.. Next up are apps that require some kind of data persistence but aren’t collaborative in any way. We categorized these under “Medium” difficulty because you still need to work with some kind of in-browser storage solution.

“Hard” is where things get really interesting. Not only do we need to cache static assets and make use of local data storage, we need to think about how these apps can send and receive data to and from other users when they do get back online . Email without extremely large attachments, turn based games like Chess, and project management apps such as Trello, Pivotal Tracker, and Basecamp could all be converted to an offline-first architecture. These are the kinds of applications we were attempting to make simpler for developers to build as offline-first.

Before moving on, we just want to briefly mention the last class of apps on this chart. These would be pretty much impossible to convert to an offline-first architecture. Apps such as Twitch and Facebook aren’t able to adopt an offline-first approach while keeping some of their core functionalities. Streaming for example, requires a persistent and reliable internet connection. Add on extremely large data sets and we have a situation where we don’t even have enough hard drive space to store that information. We put chat apps in this category too because even though they have the potential of being offline-first, a disconnected chat app might as well be email.

turtleDB Architecture