explaingit

nozbe/watermelondb

★ 11,687JavaScriptAudience · developerComplexity · 3/5LicenseSetup · moderate

TLDR

WatermelonDB is a fast local database for React and React Native apps that loads only what you need, keeps the UI smooth with background SQLite queries, and auto-refreshes components when data changes.

Mindmap

mindmap
  root((WatermelonDB))
    What it does
      Local SQLite storage
      Lazy data loading
      Reactive UI updates
    Platforms
      iOS
      Android
      Web and Node.js
    Key concepts
      Models and schemas
      Background threads
      Server sync
    Audience
      React Native devs
      Mobile app builders
      Offline-first apps
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Store tens of thousands of records in a React Native app and keep the UI fast by reading only the data currently on screen.

USE CASE 2

Build a task-management or note-taking app where changes in one screen automatically refresh related components anywhere in the app.

USE CASE 3

Set up offline-first data storage in a React app and sync changes with your own server backend when connectivity is available.

Tech stack

JavaScriptTypeScriptReact NativeSQLiteRxJSFlow

Getting it running

Difficulty · moderate Time to first run · 30min

Requires native SQLite setup for iOS and Android, follow the platform-specific installation steps in the docs carefully.

Use freely for any purpose, including commercial use, as long as you keep the copyright notice (MIT).

In plain English

WatermelonDB is a local database library built for mobile and web apps that use React or React Native. It is designed to keep apps feeling fast even when they store large amounts of data, tens of thousands of records or more. The project has been in production use at Nozbe, a task management company, since 2017, and a number of other apps including Mattermost and Rocket.Chat also use it. The core idea is that WatermelonDB does not load all your data into memory at once. Instead it reads only the records you actually request at the moment you need them. All queries run directly against a built-in SQLite database on a separate background thread, so the main interface thread stays free and the app launches quickly. This matters most on lower-end Android devices, where loading a large dataset into JavaScript at startup can make an app feel slow. The other main feature is that WatermelonDB is reactive. When you connect a component in your app's interface to a piece of data, the component will automatically update any time that data changes, no matter where in the app the change happened. You do not have to manually check whether something changed or write extra code to refresh the screen. A developer defines models (the shape of their data, like posts and comments) and then connects those models to interface components using a provided helper. The library handles the rest. WatermelonDB also supports syncing with a server backend, though the sync system requires you to provide your own backend API. It works on iOS, Android, the web, and Node.js. You can use it with TypeScript or Flow for static type checking. The optional reactive API is built on RxJS, but RxJS is not required. The project is open source under the MIT license, meaning it is free to use in personal and commercial projects.

Copy-paste prompts

Prompt 1
Set up WatermelonDB in a new React Native project, show me how to define a Post model with title, body, and author fields, then connect it to a FlatList component.
Prompt 2
I am building an offline-first app with WatermelonDB, show me how to implement a sync function that pushes local changes to my REST API and pulls remote updates.
Prompt 3
How do I query all posts in WatermelonDB where author equals a given name, sorted by creation date, and observe that query so my React component re-renders automatically when results change?
Prompt 4
Walk me through adding WatermelonDB to an existing React Native Android project, including the native SQLite linking steps.
Open on GitHub → Explain another repo

← nozbe on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.