Skip to content
Get packs

WatermelonDB

A database library for React and React Native apps that loads data lazily and updates the UI when data changes

GitHub Download source
Stars
11.8k
Forks
663
Licence
MIT
Language
JavaScript
Last update
2 months ago
Type
Library

What it is

WatermelonDB is a database layer for React and React Native apps, built on top of SQLite. It loads records only when they are requested, so apps with large amounts of data can start quickly. When a record changes, the parts of the interface that depend on it update automatically.

  • Keep a to-do list responsive when it holds tens of thousands of tasks
  • Let a chat or messaging app show local data while offline and sync later
  • Re-render task counters and lists automatically when a task is completed

Great for

  • React Native developers building apps with thousands or more records
  • Teams building offline-first apps that need to sync with their own backend
  • Developers who want UI components to update automatically when data changes

Not ideal for

  • Simple apps with little data, where the README suggests Redux or MobX with a persistence adapter is easier
  • Projects that do not use React or JavaScript, since the README describes it as React-focused, though it offers a JS API for other frameworks
Step-by-step guide: how to use WatermelonDBInstall, first run, examples, tips and FAQs
WatermelonDB alternativesredux-persist vs WatermelonDBFormily vs WatermelonDB

How to get it

  1. 1

    Install with a package manager

    You'll need: Node.js · React or React Native project

    Install the npm package

    npm install @nozbe/watermelondb
  2. 2

    Run it

    • Install the package with npm.
    • Define Model classes with fields and relations, as shown in the README.
    • Set up a database with your models and an adapter.
    • Wrap components with withObservables to make them reactive.
  3. 3

    Get the most out of it

    • Use the optional RxJS API if you want observable streams
    • Use Flow or TypeScript for static typing, as the README describes
    • Read the full documentation at nozbe.github.io/WatermelonDB for sync setup
    • Check the Sync section at watermelondb.dev for connecting to your own backend

Downloads

Source code (.zip)master branch · straight from GitHubOfficial website & docswatermelondb.dev

Strengths

  • Lazy loading keeps app launch fast as data grows, according to the README
  • Queries run directly on SQLite on a separate native thread
  • Has been used in production by Nozbe since 2017, per the README

Trade-offs

  • Sync with your own backend is a feature you must set up yourself; the README only links to documentation for it
  • Requires learning its model and decorator-based API before it is productive
  • Less useful for small apps where a simpler state library is enough

How it compares

ProjectStarsTypeLevelUpdatedBest for
WatermelonDB (this)11.8kLibraryintermediate2 months agoReact Native developers building apps with thousands or more records
redux-persist12.9kLibraryintermediate30 days agoWeb developers who want Redux state to survive a page reload
react-hook-form44.9kLibraryintermediate5 days agoReact developers building forms with several fields
duckdb42.7kLibrarybeginner4 days agoAnalysts who want to run SQL directly on CSV, Parquet, or JSON files
typeorm36.7kLibraryintermediate8 days agoNode.js or TypeScript developers building apps backed by a relational database
solid36.2kLibraryintermediate4 days agoDevelopers who want fine-grained control over what re-renders in a web UI

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.