Guide · Open source

How to use WatermelonDB: models, reactive components and setup

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

WatermelonDB is a database layer for React and React Native apps, built on top of SQLite. It loads records only when they are requested and updates the parts of the interface that depend on a record when that record changes. This guide covers what it is good for, how to install it, how to define models and connect components, and when another tool is a better choice.

WatermelonDBNozbe/WatermelonDB · ★ 11.8k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm you have Node.js and a React or React Native project.
2Install the package. Run npm install @nozbe/watermelondb in your project folder.
3Define your models. Create model classes with @field and @children decorators that match your data.
4Wrap components. Use withObservables to subscribe each component to the records it displays.
5Render related data. Pass relations such as post.comments into the enhanced parent component and render children with keys.
6Read the full docs. Follow the documentation at https://nozbe.github.io/WatermelonDB/ for setup details beyond this example.

What WatermelonDB is good for

WatermelonDB is aimed at React Native apps that hold thousands or more records. The README says the number one goal is real-world performance, and that loading a full database into JavaScript is expensive, which is why WatermelonDB loads data lazily. Queries run directly on SQLite on a separate native thread.

Apps with large amounts of data that need to launch quickly
Offline-first apps that sync with your own backend
UI components that should update automatically when data changes

Install WatermelonDB with npm

You need Node.js and a React or React Native project. Install the npm package from your project folder with the command below.

Prerequisites: Node.js and a React or React Native project
The package is published on npm as @nozbe/watermelondb

npm install @nozbe/watermelondb

Define models for your data

A model maps a table to a JavaScript class. In the README example, a Post model has a name and body field and a children relation to comments, and a Comment model has a body and an author field. The decorators @field and @children connect class properties to the stored data.

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

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

Connect components so they update automatically

Wrap a component with withObservables to subscribe it to specific records. The README says that when a post or comment is added, changed or removed, the right components re-render on their own. The wrapped component receives the observed record as a prop, and the enhancer can also pass relations such as post.comments.

withObservables takes a list of prop names to watch, then returns the props to pass in
Changes in unrelated parts of the app also propagate without extra wiring, according to the README

const enhance = withObservables(['comment'], ({ comment }) => ({
  comment,
}))
const EnhancedComment = enhance(Comment)

Render a parent record with its children

The parent component receives the post and its comments, maps over the comments and renders the enhanced child component for each one. Keep the key prop on each child, as with any React list.

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
}))

Know when to choose something else

The README says that for simple apps with little data, Redux or MobX with a persistence adapter is easier. It also describes WatermelonDB as React-focused, although it offers a JS API for other UI frameworks. Projects in other languages or with small data sets may be better served by a simpler option. The README lists Realm, Redux Persist and PouchDB as comparable projects.

What people use it for

A to-do app where completing a task re-renders the task, its list and task counters
A posts and comments screen where new comments appear without manual refresh logic
An offline-first app that syncs local records with the developer's own backend
A React Native app with thousands of records that must launch quickly on slower Android devices

Frequently asked questions

Is WatermelonDB free to use?

WatermelonDB is available under the MIT license, as stated in the README. The LICENSE file in the repository has the full terms.

What do I need to install WatermelonDB?

The README lists Node.js and a React or React Native project as prerequisites. Install the package with npm install @nozbe/watermelondb.

Does WatermelonDB work outside React Native?

The README says it is React-focused but offers a JS API for other UI frameworks. The feature list also mentions iOS, Android, Windows, web and Node.js.

Is WatermelonDB a good fit for a small app?

Probably not. The README says that for simple apps, using Redux or MobX with a persistence adapter is the easiest way to go.

What are the alternatives to WatermelonDB?

The README lists Realm and Redux Persist as comparable projects. PouchDB is also named as an alternative in the project information.

Does WatermelonDB support sync?

The README says it is offline-first and can sync with your own backend. See the Sync documentation at https://watermelondb.dev/docs/Sync/Intro for details.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

WatermelonDB suits React and React Native developers building apps with thousands or more records, especially offline-first apps that sync with their own backend. If your app is small or not based on React or JavaScript, the README suggests simpler options such as Redux or MobX with a persistence adapter, or a comparable project like Realm or PouchDB.

Install options & downloads