Installation
First, add Watermelon to your project:
yarn add @nozbe/watermelondb
# (or with npm:)
npm install @nozbe/watermelondb
React Native setup
Install the Babel plugin for decorators if you haven't already:
yarn add --dev @babel/plugin-proposal-decorators
# (or with npm:)
npm install -D @babel/plugin-proposal-decoratorsAdd ES6 decorators support to your
.babelrc
file:{
"presets": ["module:metro-react-native-babel-preset"],
"plugins": [["@babel/plugin-proposal-decorators", { "legacy": true }]]
}Set up your iOS or Android project — see instructions below
iOS (React Native)
At least Xcode 13.x and iOS 15 are recommended (earlier versions are not tested for compatibility).
Set up Babel config in your project
See instructions above ⬆️
Link WatermelonDB's native library (using CocoaPods)
Open your
Podfile
and add this:# Uncomment this line if you're not using auto-linking or if auto-linking causes trouble
# pod 'WatermelonDB', path: '../node_modules/@nozbe/watermelondb'
# WatermelonDB dependency, should not be needed on modern React Native
# (please file an issue if this causes issues for you)
# pod 'React-jsi', path: '../node_modules/react-native/ReactCommon/jsi', modular_headers: true
# WatermelonDB dependency
pod 'simdjson', path: '../node_modules/@nozbe/simdjson', modular_headers: trueMake sure you run
pod install
(orbundle exec pod install
) after updatingPodfile
.We highly recommend that you do not use frameworks. If WatermelonDB fails to build in the frameworks mode for you, use this workaround to force building it in static library mode.
Manual (non-CocoaPods) linking is not supported.
Android (React Native)
Set up Babel config in your project
See instructions above ⬆️
Linking Manually
By default, React Native uses autolinking, and you don't need the steps below! Only use this with old versions of React Native or if you opt out of autolinking.
- In
android/settings.gradle
, add:
include ':watermelondb'
project(':watermelondb').projectDir =
new File(rootProject.projectDir, '../node_modules/@nozbe/watermelondb/native/android')
- In
android/app/build.gradle
, add:
// ...
dependencies {
// ...
implementation project(':watermelondb') // ⬅️ This!
}
- And finally, in
android/app/src/main/java/{YOUR_APP_PACKAGE}/MainApplication.java
, add:
// ...
import com.nozbe.watermelondb.WatermelonDBPackage; // ⬅️ This!
// ...
@Override
protected List<ReactPackage> getPackages() {
return Arrays.<ReactPackage>asList(
new MainReactPackage(),
new WatermelonDBPackage() // ⬅️ Here!
);
}
Using with react-native-screens or react-native-gesture-handler
Troubleshooting
Can't find variable: Symbol
You're using an ancient version of JSC. Install jsc-android
or Hermes.
JSI Installation (Optional, recommended)
To enable fast, highly performant, synchronous JSI operation on Android, you need to take a few additional steps manually.
Make sure you have NDK installed (version
20.1.5948944
has been tested to work when writing this guide)In
android/settings.gradle
, add:include ':watermelondb-jsi'
project(':watermelondb-jsi').projectDir =
new File(rootProject.projectDir, '../node_modules/@nozbe/watermelondb/native/android-jsi')In
android/app/build.gradle
, add:// ...
android {
// ...
packagingOptions {
pickFirst '**/libc++_shared.so' // ⬅️ This (if missing)
}
}
dependencies {
// ...
implementation project(':watermelondb-jsi') // ⬅️ This!
}If you're using Proguard, in
android/app/proguard-rules.pro
add:-keep class com.nozbe.watermelondb.** { *; }
And finally, in
android/app/src/main/java/{YOUR_APP_PACKAGE}/MainApplication.java
, add:// ...
import com.nozbe.watermelondb.jsi.WatermelonDBJSIPackage; // ⬅️ This!
import com.facebook.react.bridge.JSIModulePackage; // ⬅️ This!
// ...
private final ReactNativeHost mReactNativeHost =
new ReactNativeHost(this) {
// ...
@Override
protected JSIModulePackage getJSIModulePackage() {
return new WatermelonDBJSIPackage(); // ⬅️ This!
}
}or if you have multiple JSI Packages (for example, when using
reanimated
):// ...
import java.util.Arrays; // ⬅️ This!
import com.facebook.react.bridge.JSIModuleSpec; // ⬅️ This!
import com.facebook.react.bridge.JSIModulePackage; // ⬅️ This!
import com.facebook.react.bridge.ReactApplicationContext; // ⬅️ This!
import com.facebook.react.bridge.JavaScriptContextHolder; // ⬅️ This!
import com.nozbe.watermelondb.jsi.WatermelonDBJSIPackage; // ⬅️ This!
// ...
private final ReactNativeHost mReactNativeHost =
new ReactNativeHost(this) {
// ...
@Override
protected JSIModulePackage getJSIModulePackage() {
return new JSIModulePackage() {
@Override
public List<JSIModuleSpec> getJSIModules(
final ReactApplicationContext reactApplicationContext,
final JavaScriptContextHolder jsContext
) {
List<JSIModuleSpec> modules = Arrays.asList();
modules.addAll(new WatermelonDBJSIPackage().getJSIModules(reactApplicationContext, jsContext)); // ⬅️ This!
// ⬅️ add more JSI packages here by conventions above, for example:
// modules.addAll(new ReanimatedJSIModulePackage().getJSIModules(reactApplicationContext, jsContext));
return modules;
}
};
}
}
Troubleshooting JSI issues
If you see a crash at launch similar to this after updating React Native:
signal 11 (SIGSEGV), code 2 (SEGV_ACCERR), fault addr 0x79193ac4a9
(...)
backtrace:
(...)
watermelondb::createMethod(facebook::jsi::Runtime&, facebook::jsi::Object&, char const*, unsigned int, std::__ndk1::function<facebook::jsi::Value (facebook::jsi::Runtime&, facebook::jsi::Value const*)>)+88
watermelondb::Database::install(facebook::jsi::Runtime*)+96)
(...)
… this is most likely due to broken libc++_shared
. Run ./gradlew clean
from native/android
, then try again.
Web setup
This guide assumes you use Webpack as your bundler.
If you haven't already, install Babel plugins for decorators, static class properties, and async/await to get the most out of Watermelon. This assumes you use Babel 7 and already support ES6 syntax.
yarn add --dev @babel/plugin-proposal-decorators
yarn add --dev @babel/plugin-proposal-class-properties
yarn add --dev @babel/plugin-transform-runtime
# (or with npm:)
npm install -D @babel/plugin-proposal-decorators
npm install -D @babel/plugin-proposal-class-properties
npm install -D @babel/plugin-transform-runtimeAdd ES7 support to your
.babelrc
file:{
"plugins": [
["@babel/plugin-proposal-decorators", { "legacy": true }],
["@babel/plugin-proposal-class-properties", { "loose": true }],
[
"@babel/plugin-transform-runtime",
{
"helpers": true,
"regenerator": true
}
]
]
}
Windows (React Native)
WatermelonDB has experimental support for React Native Windows.
To set up:
- Set up Babel config in your project - See instructions above for all React Native platforms
- Run
npx react-native autolink-windows
to perform autolinking. See section below if you don't use autolinking.
Caveats to keep in mind about React Native Windows support:
- Windows support is new and experimental
- Only JSI port is available, so you must initialize
SQLiteAdapter
with{ jsi: true }
- JSI means that Remote Debugging (WebDebugger) is not available. Use direct debugging.
- Enable Hermes when using WatermelonDB on RNW. Chakra has not been tested and may not work.
- Turbo Sync has not been implemented
- onDestroy event has not been implemented. This only causes issues if you need to reload JS bundle at runtime (other than in development).
Linking Manually
By default, React Native uses autolinking, and you don't need the steps below!
Follow instructions on React Native Windows website, noting that:
- Path to vcxproj:
node_modules\@nozbe\watermelondb\native\windows\WatermelonDB\WatermelonDB.vcxproj
- Name of project to reference:
WatermelonDB
- Header for PCH:
#include "winrt/WatermelonDB.h"
- Package provider:
PackageProviders().Append(winrt::WatermelonDB::ReactPackageProvider());
NodeJS (SQLite) setup
You only need this if you want to use WatermelonDB in NodeJS with SQLite (e.g. for scripts that share code with your web/React Native app)
Install better-sqlite3 peer dependency
yarn add --dev better-sqlite3
# (or with npm:)
npm install -D better-sqlite3
Next steps
➡️ After Watermelon is installed, set it up