WatermelonDB is a native package that lets you make your app offline first, so it works without using the Internet. The issue with WatermelonDB is that you can't use it with an Expo-managed workflow.

To fix this issue, a while ago, we created a WatermelonDB plugin, which automatically does the initial configuration and allows you to use WatermelonDB with the Expo build system EAS.

The plugin has recently been added to the official Expo Config plugin list.
In this blog,
Morrow’s senior developer Costas talks you through how to use WatermelonDB with Expo.

WatermelonDB is an open-source, reactive database framework for mobile and web applications. It is designed to provide a seamless experience for developers, with an easy-to-use API and support for real-time updates

WatermelonDB also prioritises offline-first functionality, allowing your app to function even without an internet connection. It is optimised for building complex applications in React Native, and the number one goal is real-world performance.

All querying is performed directly on the rock-solid SQLite database on a separate native thread, so most queries resolve in an instant.

Use WatermelonDB with React Native Expo

Because WatermelonDB is a native module, it can’t be used directly in Expo projects as is. You would have to eject to “bare workflow”, thus having to manage native code on your own and missing all of Expo’s “managed workflow” benefits.

But with the help of @morrowdigital/watermelondb-expo-plugin you can use WatermelonDB in your Expo project in “managed workflow”. No need to eject, no need to manage native code.

Installing WatermelonDB

First step before installing the plugin, is to install WatermelonDB itself.



Installing watermelondb-expo-plugin

First, make sure you have installed expo-build-properties. This is a prerequisite for the plugin to work.

*Please note: We tested this against Expo SDK 49.

Then install the plugin, using your favourite package manager.


Finally, make sure to add the plugin to your app.json:

You are now able to rebuild your app

A quick intro to WatermelonDB

Let’s see a small example of an app wanting to store a list of users’ favourite board games.

First, we have to define a schema for our database. Schema defines the tables, columns, and relationships between tables.

Here’s a simple one for a list of board games:

Next, we create our models. A model binds a Javascript class to a database table. Models are used to create, update, and delete records in the database.

Moving on, we have to create a database instance.

All modifications to the database (like creating, updating, and deleting records) must be done in a Writer, either by wrapping your work in database.write() or by using special decorators in the model (see documentation). We have to provide a callback function which will receive an object that needs to be updated with the data to be saved.

Also, to obtain data from the database, we use queries.

We can now provide this query to a component and use it to render a list of board games.

And our GameList component can use the query to render a list of games. Nothing special here, just a simple React component.

But the problem above is that the component is not reactive. Changes to the database content and our query will not update the component. We need to use withObservables HOC to wrap our component and make it reactive.

This way, our list becomes re-active and will update itself when the database changes. You can find out more about withObservables here: https://watermelondb.dev/Components.html?#understanding-withobservables.


Above, we saw you can use the WatermelonDB expo plugin and scratched the surface of what WatermelonDB can do. You can find out more about it in the documentation.

Happy Coding!

Liked this tutorial? Share it with your friends and colleagues, and make sure to sign up for our monthly newsletter!

More insights