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
Using with react-native-screens or react-native-gesture-handler
Troubleshooting
JSI Installation (Optional, recommended)
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
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