WatermelonDB is an MIT-licensed, open-source reactive database framework for JavaScript that keeps React and React Native apps launching fast by loading records lazily from a SQLite foundation instead of pulling an entire dataset into JavaScript.

What it is

WatermelonDB is a database framework written in JavaScript for React and React Native applications, published under the MIT licence and developed in the open by Nozbe. It sits on top of SQLite as its storage engine and adds a model layer, so developers define classes with decorators such as @field and @children to describe records and their relations. On top of those models it provides an observable layer, exposed through the withObservables higher-order component and an optional RxJS API. It supports static typing with either Flow or TypeScript, and it runs across iOS, Android, Windows, web, and Node.js. The project has been in production since 2017, where it powers Nozbe, and its documentation lives at watermelondb.dev.

The concrete problem it solves is application launch time on data-heavy apps. The README states plainly that for simple apps, using Redux or MobX with a persistence adapter is the easiest approach, but that once an app scales to thousands or tens of thousands of records, loading a full database into JavaScript becomes expensive and the app becomes slow to launch, especially on slower Android devices. WatermelonDB replaces that pattern by being lazy: nothing is loaded until it is requested, and querying runs directly against SQLite on a separate native thread, so most queries resolve immediately. Unlike using SQLite directly, the framework is fully observable, so changing a record automatically re-renders every piece of UI that depends on it, including lists that must reorder and counters that must update.

Key capabilities

• Lazy loading: no records are read from SQLite until a component or query actually asks for them, which keeps launch time flat as the dataset grows.
• Relational models defined in JavaScript with decorators such as @field and @children, backed by SQLite.
• Querying executed directly against the SQLite database on a separate native thread rather than in JavaScript.
• Reactive rendering through the withObservables higher-order component, which re-renders dependent components when a post, comment, or other record is added, changed, or removed.
• An optional RxJS API for teams that prefer observable streams over the component-level integration.
• Offline-first operation with synchronization against a backend the developer provides.
• Static typing through Flow or TypeScript, and a framework-agnostic JavaScript API for plugging into UI frameworks other than React.

Who uses it and how

• Production React Native apps that carry thousands to tens of thousands of records and need the app to open instantly regardless of dataset size.
• Teams that outgrow Redux or MobX paired with a persistence adapter, where the full store is loaded into JavaScript at startup.
• Offline-first mobile products that must keep working without connectivity and reconcile changes through a sync layer against an in-house backend.
• Cross-platform codebases targeting iOS, Android, Windows, web, and Node.js from the same model definitions.
• Contributors: the repository carries the hacktoberfest topic and maintains a good first issue label for newcomers, with setup and testing guidance in CONTRIBUTING.md.

Getting started

The README excerpt does not print an install or run command, so the entry point is the full documentation at watermelondb.dev and the repository docs at nozbe.github.io/WatermelonDB, with project setup, testing, and environment instructions in CONTRIBUTING.md.

How it compares

The tools named in the facts are Redux and MobX used with a persistence adapter, and SQLite used directly. Redux and MobX are described as the easiest choice for simple apps, while WatermelonDB targets complex applications where loading the whole database into JavaScript is the bottleneck; against raw SQLite, the difference is observability, since SQLite on its own will not re-render components when a record changes.

When to use it — and when not to

A self-hoster takes on the SQLite database itself and, for offline-first use, the sync backend on the other end, because the framework synchronizes with a backend the developer supplies rather than hosting one. The repository shows 304 open issues, and the "Who uses WatermelonDB" section is still an empty placeholder inviting pull requests, so the published adopter list is not yet evidence of ecosystem breadth. Teams building a simple app should follow the README's own advice and start with Redux or MobX plus a persistence adapter rather than adopting this framework.

class Post extends Model {
  @field('name') name
  @field('body') body
  @children('comments') comments
}

class Comment extends Model {
  @field('body') body
  @field('author') author
}

const Comment = ({ comment }) => (
  <View style={styles.commentBox}>
    <Text>{comment.body} — by {comment.author}</Text>
  </View>
)

// This is how you make your app reactive! ✨
const enhance = withObservables(['comment'], ({ comment }) => ({
  comment,
}))
const EnhancedComment = enhance(Comment)

const Post = ({ post, comments }) => (
  <View>
    <Text>{post.name}</Text>
    <Text>Comments:</Text>
    {comments.map(comment =>
      <EnhancedComment key={comment.id} comment={comment} />
    )}
  </View>
)

const enhance = withObservables(['post'], ({ post }) => ({
  post,
  comments: post.comments
}))