A tutorial on how to use WatermelonDB with React Native Expo

Note: this blog was updated to the latest version of “WatermelonDB config plugin” v2.3.1, which supports Expo SDK 50.

‍

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 been added to the official Expo Config plugin list.
In this blog, Morrow’s senior React Native developer, Costas, talks you through how to use WatermelonDB with Expo.

‍

Read: "React Native developers, here are the top 5 reasons why you should consider using Expo in 2024".

‍

Looking for Expo Support? Book a free 30-minute consultation with our expert team.

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.

‍

Read "Balancing between platforms: Native and Web app development with Tamagui".

‍

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.

‍

Read: "An Updated Developer's Guide to Taming Expo’s Environmental Variables (in Expo SDK v49)".

‍

Installing WatermelonDB

‍

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

So:

or:

‍

Read: Enhancing Your Tamagui Apps: Media Queries and Animations.

‍

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 and 50.

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

‍

Read: "React Native Year in Review 2023 - Key Updates & Highlights".

‍

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.

‍

‍
Read: "React Native developers, here are the top 5 reasons why you should consider using Expo in 2024".

‍

Conclusion

‍

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.

To find a fully working example, see the morrowdigital/watermelondb-plugin-example repository, along with an example of how to set up Offline-First state management with WatermelonDB and Supabase.

‍

Happy Coding!

‍

Liked this tutorial? Share it with your friends and colleagues, and make sure to sign up for our monthly newsletter, where we share dev tutorials, business updates and tech news.

‍