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-decorators

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

Set up Babel config in your project

See instructions above ⬆️
Add Swift support to your Xcode project:
- Open ios/YourAppName.xcodeproj in Xcode
- Right-click on (your app name) in the Project Navigator on the left, and click New File…
- Create a single empty Swift file (wmelon.swift) to the project (make sure that Your App Name target is selected when adding), and when Xcode asks, press Create Bridging Header and do not remove the Swift file afterwards

Link WatermelonDB's native library using CocoaPods

Add this to your Podfile:

# If you're using autolinking, this line might not be needed
pod 'WatermelonDB', :path => '../node_modules/@nozbe/watermelondb'

# NOTE: Do not remove, needed to keep WatermelonDB compiling:
pod 'React-jsi', :path => '../node_modules/react-native/ReactCommon/jsi', :modular_headers => true

# NOTE: This is required as of v0.23
pod 'simdjson', path: '../node_modules/@nozbe/simdjson'

Make sure you run pod install after updating Podfile

Note that as of WatermelonDB 0.22, manual (non-CocoaPods) linking is not supported.

At least Xcode 12.2 and iOS 13 are recommended (earlier versions are not tested for compatibility).

Fix up your Bridging Header

You will likely see that the iOS build fails to compile. If this happens, locate the Swift Bridging Header (likely ios/YourAppName/YourAppName-Bridging-Header.h), and paste this:
```
#import <React/RCTBundleURLProvider.h>
#import <React/RCTRootView.h>
#import <React/RCTViewManager.h>
#import <React/RCTBridgeModule.h>

// Silence warning
#import "../../node_modules/@nozbe/watermelondb/native/ios/WatermelonDB/SupportingFiles/Bridging.h"
```
You might have to tweak the import path to correctly locate Watermelon's bridging header.

Android (React Native)

Set up Babel config in your project

See instructions above ⬆️

On RN60+, auto linking should work.

Linking Manually

Users on React Native 0.60+ automatically have access to "autolinking", requiring no further manual installation steps. If you are on React Native 0.60+ please skip this section. If you are on React Native < 0.60 please do the following in addition to the previous steps:

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

Custom Kotlin Version ⚠️

Make sure the kotlin version is set to 1.3.50 or above. Just set ext properties `kotlinVersion` in `android/build.gradle`, and WatermelonDB will use the specified kotlin version.

buildscript {
    ext.kotlinVersion = '1.3.50'
}

Using with react-native-screens or react-native-gesture-handler

If you are using recent versions of react-native-screens or react-native-gesture-handler, you will need to set the kotlin version to 1.5.20 or above.

See instructions above ⬆️

Troubleshooting

If you get this error:

Can't find variable: Symbol

You're using an ancient version of JSC. Install jsc-android or Hermes.

JSI Installation (Optional)

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:

// ...
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

           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-runtime

Add 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
       }
    ]
  ]
}

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

WatermelonDB documentation