@rikishi/watermelondb

<!DOCTYPE HTML> <html lang="en" class="sidebar-visible no-js light"> <head>  <meta charset="UTF-8"> <title>Installation - WatermelonDB documentation</title>  <meta content="text/html; charset=utf-8" http-equiv="Content-Type"> <meta name="description" content=""> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="theme-color" content="#ffffff" /> <link rel="icon" href="favicon.svg"> <link rel="shortcut icon" href="favicon.png"> <link rel="stylesheet" href="css/variables.css"> <link rel="stylesheet" href="css/general.css"> <link rel="stylesheet" href="css/chrome.css"> <link rel="stylesheet" href="css/print.css" media="print">  <link rel="stylesheet" href="FontAwesome/css/font-awesome.css"> <link rel="stylesheet" href="fonts/fonts.css">  <link rel="stylesheet" href="highlight.css"> <link rel="stylesheet" href="tomorrow-night.css"> <link rel="stylesheet" href="ayu-highlight.css">  </head> <body>  <script type="text/javascript"> var path_to_root = ""; var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light"; </script>  <script type="text/javascript"> try { var theme = localStorage.getItem('mdbook-theme'); var sidebar = localStorage.getItem('mdbook-sidebar'); if (theme.startsWith('"') && theme.endsWith('"')) { localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1)); } if (sidebar.startsWith('"') && sidebar.endsWith('"')) { localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1)); } } catch (e) { } </script>  <script type="text/javascript"> var theme; try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { } if (theme === null || theme === undefined) { theme = default_theme; } var html = document.querySelector('html'); html.classList.remove('no-js') html.classList.remove('light') html.classList.add(theme); html.classList.add('js'); </script>  <script type="text/javascript"> var html = document.querySelector('html'); var sidebar = 'hidden'; if (document.body.clientWidth >= 1080) { try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { } sidebar = sidebar || 'visible'; } html.classList.remove('sidebar-visible'); html.classList.add("sidebar-" + sidebar); </script> <nav id="sidebar" class="sidebar" aria-label="Table of contents"> <div class="sidebar-scrollbox"> <ol class="chapter"><li class="chapter-item expanded "><a href="ch01-00-get-excited.html"><strong aria-hidden="true">1.</strong> Get excited</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="index.html"><strong aria-hidden="true">1.1.</strong> Check out the README</a></li><li class="chapter-item expanded "><a href="Demo.html"><strong aria-hidden="true">1.2.</strong> See the demo</a></li></ol></li><li class="chapter-item expanded "><a href="ch02-00-learn-to-use.html"><strong aria-hidden="true">2.</strong> Learn to use Watermelon</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="Installation.html" class="active"><strong aria-hidden="true">2.1.</strong> Installation</a></li><li class="chapter-item expanded "><a href="Setup.html"><strong aria-hidden="true">2.2.</strong> Setup</a></li><li class="chapter-item expanded "><a href="Schema.html"><strong aria-hidden="true">2.3.</strong> Schema</a></li><li class="chapter-item expanded "><a href="Model.html"><strong aria-hidden="true">2.4.</strong> Defining Models</a></li><li class="chapter-item expanded "><a href="CRUD.html"><strong aria-hidden="true">2.5.</strong> Create, Read, Update, Delete</a></li><li class="chapter-item expanded "><a href="Components.html"><strong aria-hidden="true">2.6.</strong> Connecting to React Components</a></li><li class="chapter-item expanded "><a href="Query.html"><strong aria-hidden="true">2.7.</strong> Querying</a></li><li class="chapter-item expanded "><a href="Relation.html"><strong aria-hidden="true">2.8.</strong> Relations</a></li><li class="chapter-item expanded "><a href="Writers.html"><strong aria-hidden="true">2.9.</strong> Writers, Readers, batching</a></li></ol></li><li class="chapter-item expanded "><a href="ch03-00-advanced.html"><strong aria-hidden="true">3.</strong> Advanced guides</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="Advanced/Migrations.html"><strong aria-hidden="true">3.1.</strong> Migrations</a></li><li class="chapter-item expanded "><a href="Advanced/Sync.html"><strong aria-hidden="true">3.2.</strong> Sync</a></li><li class="chapter-item expanded "><a href="Advanced/CreateUpdateTracking.html"><strong aria-hidden="true">3.3.</strong> Automatic create/update tracking</a></li><li class="chapter-item expanded "><a href="Advanced/AdvancedFields.html"><strong aria-hidden="true">3.4.</strong> Advanced fields</a></li><li class="chapter-item expanded "><a href="Advanced/Flow.html"><strong aria-hidden="true">3.5.</strong> Flow</a></li><li class="chapter-item expanded "><a href="Advanced/LocalStorage.html"><strong aria-hidden="true">3.6.</strong> LocalStorage</a></li><li class="chapter-item expanded "><a href="Advanced/ProTips.html"><strong aria-hidden="true">3.7.</strong> Pro tips</a></li><li class="chapter-item expanded "><a href="Advanced/Performance.html"><strong aria-hidden="true">3.8.</strong> Performance tips</a></li><li class="chapter-item expanded "><a href="Advanced/SharingDatabaseAcrossTargets.html"><strong aria-hidden="true">3.9.</strong> iOS - Sharing database across targets</a></li></ol></li><li class="chapter-item expanded "><a href="ch04-00-deeper.html"><strong aria-hidden="true">4.</strong> Dig deeper into WatermelonDB</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="Implementation/Architecture.html"><strong aria-hidden="true">4.1.</strong> Architecture</a></li><li class="chapter-item expanded "><a href="Implementation/Adapters.html"><strong aria-hidden="true">4.2.</strong> Adapters</a></li><li class="chapter-item expanded "><a href="Implementation/SyncImpl.html"><strong aria-hidden="true">4.3.</strong> Sync implementation</a></li></ol></li><li class="chapter-item expanded "><a href="ch04-00-deeper.html"><strong aria-hidden="true">5.</strong> Other</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="Roadmap.html"><strong aria-hidden="true">5.1.</strong> Roadmap</a></li><li class="chapter-item expanded "><a href="CONTRIBUTING.html"><strong aria-hidden="true">5.2.</strong> Contributing</a></li><li class="chapter-item expanded "><a href="CHANGELOG.html"><strong aria-hidden="true">5.3.</strong> Changelog</a></li></ol></li></ol> </div> <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div> </nav> <div id="page-wrapper" class="page-wrapper"> <div class="page"> <div id="menu-bar-hover-placeholder"></div> <div id="menu-bar" class="menu-bar sticky bordered"> <div class="left-buttons"> <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar"> <i class="fa fa-bars"></i> </button> <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list"> <i class="fa fa-paint-brush"></i> </button> <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu"> <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li> <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li> <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li> <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li> <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li> </ul> <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar"> <i class="fa fa-search"></i> </button> </div> <h1 class="menu-title">WatermelonDB documentation</h1> <div class="right-buttons"> <a href="print.html" title="Print this book" aria-label="Print this book"> <i id="print-button" class="fa fa-print"></i> </a> </div> </div> <div id="search-wrapper" class="hidden"> <form id="searchbar-outer" class="searchbar-outer"> <input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header"> </form> <div id="searchresults-outer" class="searchresults-outer hidden"> <div id="searchresults-header" class="searchresults-header"></div> <ul id="searchresults"> </ul> </div> </div>  <script type="text/javascript"> document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible'); document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible'); Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) { link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1); }); </script> <div id="content" class="content"> <main> <h1 id="installation"><a class="header" href="#installation">Installation</a></h1> <p>First, add Watermelon to your project:</p> <pre><code class="language-bash">yarn add @rikishi/watermelondb # (or with npm:) npm install @rikishi/watermelondb </code></pre> <h2 id="react-native-setup"><a class="header" href="#react-native-setup">React Native setup</a></h2> <ol> <li> <p>Install the Babel plugin for decorators if you haven't already:</p> <pre><code class="language-bash">yarn add --dev @babel/plugin-proposal-decorators # (or with npm:) npm install -D @babel/plugin-proposal-decorators </code></pre> </li> <li> <p>Add ES6 decorators support to your <code>.babelrc</code> file:</p> <pre><code class="language-json">{ "presets": ["module:metro-react-native-babel-preset"], "plugins": [ ["@babel/plugin-proposal-decorators", { "legacy": true }] ] } </code></pre> </li> <li> <p>Set up your iOS or Android project — see instructions below</p> </li> </ol> <h3 id="ios-react-native"><a class="header" href="#ios-react-native">iOS (React Native)</a></h3> <ol> <li> <p><strong>Set up Babel config in your project</strong></p> <p>See instructions above ⬆️</p> </li> <li> <p><strong>Add Swift support to your Xcode project</strong>:</p> <ul> <li>Open <code>ios/YourAppName.xcodeproj</code> in Xcode</li> <li>Right-click on <strong>(your app name)</strong> in the Project Navigator on the left, and click <strong>New File…</strong></li> <li>Create a single empty Swift file (<code>wmelon.swift</code>) to the project (make sure that <strong>Your App Name</strong> target is selected when adding), and when Xcode asks, press <strong>Create Bridging Header</strong> and <strong>do not remove</strong> the Swift file afterwards</li> </ul> </li> <li> <p><strong>Link WatermelonDB's native library using CocoaPods</strong></p> <p>Add this to your <code>Podfile</code>:</p> <pre><code class="language-ruby"># If you're using autolinking, this line might not be needed pod 'WatermelonDB', :path => '../node_modules/@rikishi/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' </code></pre> <p>Note that as of WatermelonDB 0.22, manual (non-CocoaPods) linking is not supported.</p> <p>At least Xcode 12.2 and iOS 13 are recommended (earlier versions are not tested for compatibility).</p> </li> <li> <p><strong>Fix up your Bridging Header</strong></p> <p>You will likely see that the iOS build fails to compile. If this happens, locate the Swift Bridging Header (likely <code>ios/YourAppName/YourAppName-Bridging-Header.h</code>), and paste this:</p> <pre><code class="language-objc">#import <React/RCTBundleURLProvider.h> #import <React/RCTRootView.h> #import <React/RCTViewManager.h> #import <React/RCTBridgeModule.h> // Silence warning #import "../../node_modules/@rikishi/watermelondb/native/ios/WatermelonDB/SupportingFiles/Bridging.h" </code></pre> <p>You might have to tweak the import path to correctly locate Watermelon's bridging header.</p> </li> </ol> <h3 id="android-react-native"><a class="header" href="#android-react-native">Android (React Native)</a></h3> <p><strong>Set up Babel config in your project</strong></p> <p>See instructions above ⬆️</p> <p>On RN60+, auto linking should work.</p> <details> <summary>Linking Manually</summary> <p>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 <strong>addition</strong> to the previous steps:</p> <ol> <li>In <code>android/settings.gradle</code>, add:</li> </ol> <pre><code class="language-gradle">include ':watermelondb' project(':watermelondb').projectDir = new File(rootProject.projectDir, '../node_modules/@rikishi/watermelondb/native/android') </code></pre> <ol start="2"> <li>In <code>android/app/build.gradle</code>, add:</li> </ol> <pre><code class="language-gradle">// ... dependencies { // ... implementation project(':watermelondb') // ⬅️ This! } </code></pre> <ol start="3"> <li>And finally, in <code>android/app/src/main/java/{YOUR_APP_PACKAGE}/MainApplication.java</code>, add:</li> </ol> <pre><code class="language-java">// ... import com.nozbe.watermelondb.WatermelonDBPackage; // ⬅️ This! // ... @Override protected List<ReactPackage> getPackages() { return Arrays.<ReactPackage>asList( new MainReactPackage(), new WatermelonDBPackage() // ⬅️ Here! ); } </code></pre> </details> <details> <summary>Custom Kotlin Version ⚠️</summary> 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. <pre><code class="language-gradle">buildscript { ext.kotlinVersion = '1.3.50' } </code></pre> </details> <details> <summary>Troubleshooting</summary> If you get this error: <blockquote> <p><code>Can't find variable: Symbol</code></p> </blockquote> <p>You're using an ancient version of JSC. Install <a href="https://github.com/react-community/jsc-android-buildscripts"><code>jsc-android</code></a> or Hermes.</p> </details> <details> <summary>JSI Installation (Optional)</summary> <p>To enable fast, highly performant, synchronous JSI operation on Android, you need to take a few additional steps manually.</p> <ol> <li> <p>Make sure you have NDK installed (version <code>20.1.5948944</code> has been tested to work when writing this guide)</p> </li> <li> <p>In <code>android/settings.gradle</code>, add:</p> <pre><code class="language-gradle">include ':watermelondb-jsi' project(':watermelondb-jsi').projectDir = new File(rootProject.projectDir, '../node_modules/@rikishi/watermelondb/native/android-jsi') </code></pre> </li> <li> <p>In <code>android/app/build.gradle</code>, add:</p> <pre><code class="language-gradle">// ... android { // ... packagingOptions { pickFirst '**/libc++_shared.so' // ⬅️ This (if missing) } } dependencies { // ... implementation project(':watermelondb-jsi') // ⬅️ This! } </code></pre> </li> <li> <p>And finally, in <code>android/app/src/main/java/{YOUR_APP_PACKAGE}/MainApplication.java</code>, add:</p> <pre><code class="language-java">// ... 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! } } </code></pre> <p>or if you have <strong>multiple</strong> JSI Packages:</p> <pre><code class="language-java">// ... 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; } }; } } </code></pre> </li> </ol> </details> <h2 id="web-setup"><a class="header" href="#web-setup">Web setup</a></h2> <p>This guide assumes you use Webpack as your bundler.</p> <ol> <li>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. <pre><code class="language-bash">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 </code></pre> </li> <li>Add ES7 support to your <code>.babelrc</code> file: <pre><code class="language-json">{ "plugins": [ ["@babel/plugin-proposal-decorators", { "legacy": true }], ["@babel/plugin-proposal-class-properties", { "loose": true }], [ "@babel/plugin-transform-runtime", { "helpers": true, "regenerator": true } ] ] } </code></pre> </li> </ol> <h2 id="nodejs-sqlite-setup"><a class="header" href="#nodejs-sqlite-setup">NodeJS (SQLite) setup</a></h2> <p>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)</p> <ol> <li>Install <a href="https://github.com/JoshuaWise/better-sqlite3">better-sqlite3</a> peer dependency <pre><code class="language-sh">yarn add --dev better-sqlite3 # (or with npm:) npm install -D better-sqlite3 </code></pre> </li> </ol> <hr /> <h2 id="next-steps"><a class="header" href="#next-steps">Next steps</a></h2> <p>➡️ After Watermelon is installed, <a href="./Setup.html"><strong>set it up</strong></a></p> </main> <nav class="nav-wrapper" aria-label="Page navigation">  <a rel="prev" href="ch02-00-learn-to-use.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left"> <i class="fa fa-angle-left"></i> </a> <a rel="next" href="Setup.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right"> <i class="fa fa-angle-right"></i> </a> <div style="clear: both"></div> </nav> </div> </div> <nav class="nav-wide-wrapper" aria-label="Page navigation"> <a rel="prev" href="ch02-00-learn-to-use.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left"> <i class="fa fa-angle-left"></i> </a> <a rel="next" href="Setup.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right"> <i class="fa fa-angle-right"></i> </a> </nav> </div> <script type="text/javascript"> window.playground_copyable = true; </script> <script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script> <script src="mark.min.js" type="text/javascript" charset="utf-8"></script> <script src="searcher.js" type="text/javascript" charset="utf-8"></script> <script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script> <script src="highlight.js" type="text/javascript" charset="utf-8"></script> <script src="book.js" type="text/javascript" charset="utf-8"></script>  </body> </html>