What is WatermelonDB and when should I use it?

WatermelonDB is an offline-first database for React Native built on SQLite. Use it when you have more than 100 records, need offline support, or want observable queries that auto-update your UI. For smaller state, MMKV or AsyncStorage is simpler.

How does WatermelonDB sync work?

WatermelonDB ships a sync protocol that takes a pull endpoint (returns changes since the client's last sync) and a push endpoint (accepts the client's local changes). The library handles applying changes to the local SQLite database and resolving simple conflicts.

WatermelonDB or Realm for React Native?

WatermelonDB is React Native-specific, ships with a sync protocol, and uses SQLite under the hood. Realm is cross-platform, faster for some operations, and has its own sync service. Most React Native teams pick WatermelonDB for the simpler sync story.

Can I use WatermelonDB with Supabase or Firebase?

Yes. WatermelonDB sync is backend-agnostic — you implement a pull and push endpoint. With Supabase you typically use Postgres as the source of truth and write a sync endpoint that returns changes since a cursor. With Firebase you map Firestore documents to WatermelonDB records.

Offline-First React Native With WatermelonDB (The 2026 Setup)

Every React Native app hits the same wall: you ship with AsyncStorage or MMKV, things work for the first 100 users, then someone with 5,000 records opens the app and it takes six seconds to load.

That wall is the storage layer. AsyncStorage is a key-value store — fine for tokens and preferences, broken for any real data. SQLite is fast but verbose. Realm is powerful but heavy.

WatermelonDB is the answer for serious offline-first apps. It's SQLite under the hood, lazy-loaded, observable, and ships with a sync protocol. Here's the actual setup.

Why WatermelonDB (and not the alternatives)

Option	Good for	Problem
AsyncStorage	Tokens, prefs	Reads block the JS thread past a few hundred items
MMKV	Fast key-value	Same limitations as AsyncStorage — no queries
SQLite (raw)	Anything	No ORM, no observables, you write sync yourself
Realm	Anything	Heavy native binary, sync costs money, lock-in
WatermelonDB	Offline-first apps	Learning curve, you write sync (but the protocol is spec'd)

WatermelonDB is built for the case where your data outgrows key-value storage and you need real offline sync. It lazy-loads records — a list of 10,000 items renders instantly because only the visible rows are loaded into JS memory.

Step 1: Install and configure

npm install @nozbe/watermelondb
npm install --save-dev @babel/plugin-proposal-decorators