Version: 0.30.0-beta.8

Installation

Migrating from @nozbe/watermelondb?

Follow the migration guide first, then come back here for a full native install.

First, add NitromelonDB to your project:

yarn add nitromelondb

# (or with npm:)
npm install nitromelondb

React Native setup

Native SQLite on iOS, Android, and Windows uses Nitro Modules and React Native autolinking (react-native.config.js; iOS also uses the NitromelonDB podspec). simdjson is compiled into the iOS pod from vendored sources. You do not add CocoaPods or Gradle lines by hand, and you do not run a separate setup CLI. Expo is fully supported — development builds, EAS Build, and EAS Update. See Expo.

New Architecture only

NitromelonDB does not support the old React Native architecture (Paper / the legacy bridge). Enable the New Architecture. Tested on React Native 0.83+. React Native 0.87 has it on by default.

# skip if the app already depends on it:
yarn add react-native-nitro-modules

react-native-nitro-modules >=0.35.2 is required for SQLite on iOS, Android, and Windows. It is optional on web / Node / Electron. Do not add it a second time if it is already in the app.

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 / Babel config:

{
  "presets": ["module:metro-react-native-babel-preset"],
  "plugins": [["@babel/plugin-proposal-decorators", { "legacy": true }]]
}

Rebuild the native app after adding these packages. Autolinking runs as part of the usual Expo / React Native CLI flow (use_native_modules! on iOS). There is no extra setup command.

Minimums: Xcode 15+, iOS 15.1, Android minSdk 24, React Native 0.83+ with New Architecture, Windows RNW 0.84. This will not run in Expo Go.

Expo

NitromelonDB fully supports Expo development builds, EAS Build, and EAS Update. Native SQLite is not available in Expo Go. The New Architecture must stay enabled (newArchEnabled must not be false).

Install NitromelonDB and the Nitro peer:
```
npx expo install nitromelondb react-native-nitro-modules
```
Decorators still need the Babel plugin from the React Native setup above (@babel/plugin-proposal-decorators with { "legacy": true }).
Add the config plugin to app.json or app.config.js:
```
{
  "expo": {
    "plugins": ["nitromelondb"]
  }
}
```
The plugin is optional for bare React Native — autolinking is what actually links SQLite. On Expo it runs during expo prebuild (EAS Build does this for you). It does not install the old watermelondb-jsi Android module. It rejects "newArchEnabled": false.

Optional:
```
{
  "expo": {
    "plugins": [
      [
        "nitromelondb",
        { "excludeSimArch": true }
      ]
    ]
  }
}
```
excludeSimArch excludes arm64 from iOS simulator builds. Use it only if you hit No such module 'ExpoModulesCore' (or similar) on Apple Silicon simulators.

Create a development build, then run it:

npx expo prebuild
npx expo run:ios
# or
npx expo run:android

Or with EAS:

eas build --profile development
eas build --profile production

You do not need @morrowdigital/watermelondb-expo-plugin. Remove it if you used it with @nozbe/watermelondb.

The Expo notes example is examples/NotesApp.

EAS Update

EAS Update ships a new JavaScript bundle on top of an existing native binary. Models, queries, schema, and migrations live in JS, so those changes work over OTA as long as the native SQLite engine is already in the app.

Ship a new EAS Build when you bump nitromelondb, react-native-nitro-modules, or any other native dependency.

Bare React Native

npx react-native run-ios
# or
npx react-native run-android

run-ios installs pods and applies autolinking. You do not add pod 'NitromelonDB' or pod 'simdjson' to the Podfile.

Windows uses the same Nitro SQLite engine. See Windows (React Native).

We highly recommend that you do not use use_frameworks!. If you need it (RN Firebase often uses use_frameworks! :linkage => :static), prefer static linkage. If NitromelonDB fails to build in frameworks mode, use this workaround to force static libraries. Manual (non-CocoaPods) iOS linking is not supported.

Android (React Native)

Autolinking is enough. No Gradle or MainApplication changes. Manual ReactPackage registration is the old architecture and is not supported.

Details

Troubleshooting

If you get this error:

Can't find variable: Symbol

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

Android JSI package (removed)

The separate native/android-jsi Gradle module (WatermelonDBJSIPackage, libwatermelondb-jsi.so) is gone. iOS and Android SQLite go through Nitro and autolink with react-native-nitro-modules.

If you previously installed JSI manually, remove:

include ':watermelondb-jsi' from android/settings.gradle
implementation project(':watermelondb-jsi') from android/app/build.gradle
WatermelonDBJSIPackage from MainApplication

If you minify with R8 / Proguard, keep this rule:

-keep class com.nitromelondb.** { *; }

Web setup

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

Webpack

If you're using Webpack, 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
      }
    ]
  ]
}

Vite

If you're using Vite, you'll need to edit your vite.config.js file.

If you're working with React, ensure your config looks something like this:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
    plugins: [
        react({
            babel: {
                plugins: [
                    ["@babel/plugin-proposal-decorators", { "legacy": true }],
                    ["@babel/plugin-proposal-class-properties", { "loose": true }],
                    [
                        "@babel/plugin-transform-runtime",
                        {
                            "helpers": true,
                            "regenerator": true
                        }
                    ]
                ],
            }
        }),
    ]
});

If you're not using React, you can try this (untested):

import { defineConfig } from 'vite';
import babel from 'vite-plugin-babel';

export default defineConfig({
    plugins: [
        babel({
            babelConfig: {
              babelrc: false,
              configFile: false,
              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)

NitromelonDB supports React Native Windows New Architecture (RNW 0.84 / WinAppSDK / Fabric) through Nitro — the same Nitromelon HybridObject as iOS and Android.

RNW 0.84 is New Architecture only and pairs with React Native 0.84.1. Expo NotesApp is on a newer RN, so the Windows playground is a separate app: examples/NotesApp_windows.

Tools

Tool	Version / notes
Windows	Windows 10 22H2+ or Windows 11
Node.js	22.11+
Yarn	Classic (v1)
Visual Studio	2022 (MSVC v143) or 2026 (MSVC v145)
Workloads	Desktop development with C++; Windows application development (Windows App SDK / WinUI)
Windows SDK	10.0.26100 recommended (the example pins this)

If anything is missing, run RNW's dependency script from an elevated PowerShell prompt.

How Nitro is wired

react-native-nitro-modules has no official Windows autolink (nitro#168). NitromelonDB's WinAppSDK DLL is the install entry:

JS calls TurboModuleRegistry.getEnforcing('NitroModules').install(), same as iOS/Android.
native/windows exports that TurboModule. install() runs margelo::nitro::install() with RNW's CallInvoker, then registers HybridNitromelon.
The vcxproj compiles Nitro C++ from node_modules/react-native-nitro-modules/cpp plus NitromelonDB's SQLite engine.
Apps must tell RNW not to look for a Nitro Windows project (next snippet).

Longer write-up: native/windows/README.md.

Install

Skip react-native-nitro-modules if the app already has it:

yarn add nitromelondb react-native-nitro-modules

Set up Babel decorators the same way as React Native setup.

Autolinking picks up native/windows. Add this to the app react-native.config.js:

const { windowsAppDependencies } = require('nitromelondb/windows-autolink')

module.exports = {
  // ...existing project.windows...
  dependencies: windowsAppDependencies(),
}

If you link NitromelonDB with file: (a monorepo), pass { root: path.resolve(__dirname, '../path-to-nitromelondb') }.

Rebuild:

yarn react-native run-windows

Caveats:

Direct debugging only (no Remote JS Debugging)
Turbo Sync (unsafeLoadFromSync / provideSyncJson) goes through Nitro
The old UWP Paper / WMDatabaseBridge JSI installer is removed

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\nitromelondb\native\windows\NitromelonDB\NitromelonDB.vcxproj
Name of project to reference: NitromelonDB
Header for PCH: #include "winrt/NitromelonDB.h"
Package provider: PackageProviders().Append(winrt::NitromelonDB::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

Electron (SQLite) setup

You only need this if you want to use WatermelonDB in Electron with SQLite.

Install better-sqlite3 peer dependency

yarn add --dev better-sqlite3

# (or with npm:)
npm install -D better-sqlite3

Run electron rebuild on sqlite3. This step is necessary to ensure the sqlite native build (.node) is compatible with Electron's version of Node.js. If you're using Electron Forge, this step will be performed for you during build but not development.

npx electron-rebuild -f -w -t dev better-sqlite3

Next steps

➡️ After Watermelon is installed, set it up

React Native setup​

Expo​

EAS Update​

Bare React Native​

Android (React Native)​

Web setup​

Webpack​

Vite​

Windows (React Native)​

Tools​

How Nitro is wired​

Install​

NodeJS (SQLite) setup​

Electron (SQLite) setup​

Next steps​