From 7c73835cd285db995305f24d77402f303ec8facf Mon Sep 17 00:00:00 2001 From: radex Date: Thu, 25 Mar 2021 14:15:31 +0100 Subject: [PATCH] Update documentation --- docs-master/Advanced/ProTips.md | 10 +-- docs-master/Installation.md | 137 +++----------------------------- docs-master/Roadmap.md | 18 ++--- docs-master/SUMMARY.md | 1 + docs-master/Setup.md | 108 +++++++++++++++++++++++++ 5 files changed, 131 insertions(+), 143 deletions(-) create mode 100644 docs-master/Setup.md diff --git a/docs-master/Advanced/ProTips.md b/docs-master/Advanced/ProTips.md index 87346c24d..fd3886285 100644 --- a/docs-master/Advanced/ProTips.md +++ b/docs-master/Advanced/ProTips.md @@ -2,14 +2,14 @@ ## Database viewer -See this discussion: https://github.com/Nozbe/WatermelonDB/issues/710 +[See discussion](https://github.com/Nozbe/WatermelonDB/issues/710) -**Android** - you can use the new database inspector which comes with the Android Studio Beta. https://medium.com/androiddevelopers/database-inspector-9e91aa265316 . +**Android** - you can use the [new database inspector](https://medium.com/androiddevelopers/database-inspector-9e91aa265316) which comes with the Android Studio Beta. -**Via Flipper** You can also use Facebook Flipper with this plugin: https://github.com/panz3r/react-native-flipper-databases#readme . See this thread for more details: https://github.com/Nozbe/WatermelonDB/issues/653 +**Via Flipper** You can also use Facebook Flipper [with a plugin](https://github.com/panz3r/react-native-flipper-databases#readme). See [discussion](https://github.com/Nozbe/WatermelonDB/issues/653). -**iOS** - check open database path in iOS System Log (via Console for plugged-in device, or Xcode logs, or [by using `find`](https://github.com/Nozbe/WatermelonDB/issues/710#issuecomment-776255654)), then open it via `sqlite3` in the console, or an external tool like https://sqlitebrowser.org +**iOS** - check open database path in iOS System Log (via Console for plugged-in device, or Xcode logs, or [by using `find`](https://github.com/Nozbe/WatermelonDB/issues/710#issuecomment-776255654)), then open it via `sqlite3` in the console, or an external tool like [sqlitebrowser](https://sqlitebrowser.org) ## Prepopulating database on native -There's no built-in support for this. One way is to generate a SQLite DB (you can use the the Node SQLite support in 0.19.0-2 pre-release or extract it from an ios/android app), bundle it with the app, and then use a bit of code to check if the DB you're expecting it available, and if not, making a copy of the default DB — before you attempt loading DB from JS side. See this thread: https://github.com/Nozbe/WatermelonDB/issues/774#issuecomment-667981361 +There's no built-in support for this. One way is to generate a SQLite DB (you can use the the Node SQLite support in 0.19.0-2 pre-release or extract it from an ios/android app), bundle it with the app, and then use a bit of code to check if the DB you're expecting it available, and if not, making a copy of the default DB — before you attempt loading DB from JS side. [See discussion](https://github.com/Nozbe/WatermelonDB/issues/774#issuecomment-667981361) diff --git a/docs-master/Installation.md b/docs-master/Installation.md index f8f39c248..f822541fa 100644 --- a/docs-master/Installation.md +++ b/docs-master/Installation.md @@ -59,22 +59,19 @@ npm install @nozbe/watermelondb 4. **Fix up your Bridging Header** - You will likely see that the iOS build fails to compile. If this happens: + 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: - - Open the Swift Bridging Header (likely `ios/YourAppName/YourAppName-Bridging-Header.h`) - - Paste this: + ```objc + #import + #import + #import + #import - ```objc - #import - #import - #import - #import - - // Silence warning - #import "../../node_modules/@nozbe/watermelondb/native/ios/WatermelonDB/SupportingFiles/Bridging.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 + You might have to tweak the import path to correctly locate Watermelon's bridging header. ### Android (React Native) @@ -171,120 +168,8 @@ This guide assumes you use Webpack as your bundler. } ``` -If you want to use Web Worker for WatermelonDB (this has pros and cons, we recommend you start without Web Workers, and evaluate later if it makes sense for your app to use them): - -1. Install [worker-loader](https://github.com/webpack-contrib/worker-loader) Webpack plugin to add support for Web Workers to your app: - ```sh - yarn add --dev worker-loader - - # (or with npm:) - npm install -D worker-loader - ``` - -2. And add this to Webpack configuration: - ```js - // webpack.config.js - { - module: { - rules: [ - // ⬇️ Add this: - { - test: /\.worker\.js$/, - use: { loader: 'worker-loader' } - } - ] - }, - // ... - output: { - // ... - globalObject: 'this', // ⬅️ And this - } - } - ``` - -## Set up `Database` - -Create `model/schema.js` in your project: - -```js -import { appSchema, tableSchema } from '@nozbe/watermelondb' - -export default appSchema({ - version: 1, - tables: [ - // tableSchemas go here... - ] -}) -``` - -You'll need it for [the next step](./Schema.md). Now, in your `index.js`: - -```js -import { Database } from '@nozbe/watermelondb' -import SQLiteAdapter from '@nozbe/watermelondb/adapters/sqlite' - -import schema from './model/schema' -// import Post from './model/Post' // ⬅️ You'll import your Models here - -// First, create the adapter to the underlying database: -const adapter = new SQLiteAdapter({ - schema, - // optional database name or file system path - // dbName: 'myapp', - // optional migrations - // migrations, - // synchronous mode only works on iOS. improves performance and reduces glitches in most cases, but also has some downsides - test with and without it - synchronous: true, - // experimental JSI mode, a more advanced version of synchronous: true - // experimentalUseJSI: true, - // Optional, but you should implement this method: - onSetUpError: error => { - // Database failed to load -- offer the user to reload the app or log out - } -}) - -// Then, make a Watermelon database from it! -const database = new Database({ - adapter, - modelClasses: [ - // Post, // ⬅️ You'll add Models to Watermelon here - ], - actionsEnabled: true, -}) -``` - -The above will work on React Native (iOS/Android) and NodeJS. For the web, instead of `SQLiteAdapter` use `LokiJSAdapter`: - -```js -import LokiJSAdapter from '@nozbe/watermelondb/adapters/lokijs' - -const adapter = new LokiJSAdapter({ - schema, - // migrations, // optional migrations - useWebWorker: false, // recommended setting for new projects - useIncrementalIndexedDB: true, // recommended for new projects. improves performance (but incompatible with early Watermelon databases) - // dbName: 'myapp', // optional db name - // Optional, but recommended event handlers: - onIndexedDBVersionChange: () => { - // database was deleted in another browser tab (user logged out), so we must make sure we delete - // it in this tab as well - if (checkIfUserIsLoggedIn()) { - window.location.reload() - } - }, - onQuotaExceededError: (error) => { - // Browser ran out of disk space -- do something about it - }, - onSetUpError: (error) => { - // Database failed to load -- offer the user to reload the app or log out - }, -}) - -// The rest is the same! -``` - * * * ## Next steps -➡️ After Watermelon is installed, [**define your app's schema**](./Schema.md) +➡️ After Watermelon is installed, [**set it up**](./Setup.md) diff --git a/docs-master/Roadmap.md b/docs-master/Roadmap.md index a63e00446..2f273d293 100644 --- a/docs-master/Roadmap.md +++ b/docs-master/Roadmap.md @@ -1,21 +1,15 @@ # WatermelonDB Roadmap -## From today to 1.0 +Despite being called 0.xx, WatermelonDB is essentially feature-complete and relatively API stable. It's used in production by [Nozbe Teams](https://nozbe.com) and many others. -WatermelonDB is currently in active development at [Nozbe](https://nozbe.com) for use in advanced projects. It's mostly feature-complete. However, there are a few features left before we can call it 1.0. - -### v0.xxx - -- Full transactionality (atomicity) support ??? -- Field sanitizers -- Optimized tree deleting -- API improvements +We don't call it 1.0 mostly out of convenience, to allow rapid development without incrementing `major` version counter (as dictated by SemVer). We do intend to call WatermelonDB a 1.0 once we can reach a long-term stable API. ### v1.0 -Everything above plus having at least one non-trivial app using WatermelonDB in production to verify its concepts +- Optimized tree deleting +- Long term stable API ### Beyond 1.0 -- Replace `withObservables` HOC and Prefetching with a solution based on React 17 Suspense feature -- Query templates +- Full transactionality (atomicity) support? +- Field sanitizers diff --git a/docs-master/SUMMARY.md b/docs-master/SUMMARY.md index 4024437e6..7361d5cf1 100644 --- a/docs-master/SUMMARY.md +++ b/docs-master/SUMMARY.md @@ -10,6 +10,7 @@ - [Learn to use Watermelon](./ch02-00-learn-to-use.md) - [Installation](./Installation.md) + - [Setup](./Setup.md) - [Schema](./Schema.md) - [Defining Models](./Model.md) - [Create, Read, Update, Delete](./CRUD.md) diff --git a/docs-master/Setup.md b/docs-master/Setup.md new file mode 100644 index 000000000..7d33a5cb0 --- /dev/null +++ b/docs-master/Setup.md @@ -0,0 +1,108 @@ +# Set up your app for WatermelonDB + +Make sure you [installed Watermelon](./Installation.md) before proceeding. + +Create `model/schema.js` in your project. You'll need it for [the next step](./Schema.md). + +```js +import { appSchema, tableSchema } from '@nozbe/watermelondb' + +export default appSchema({ + version: 1, + tables: [ + // tableSchemas go here... + ] +}) +``` + +Similarly, create `model/migrations.js`. ([More information about migrations](./Advanced/Migrations.md)): + +```js +import { schemaMigrations } from '@nozbe/watermelondb/Schema/migrations' + +export default schemaMigrations({ + migrations: [ + // We'll add migration definitions here later + ], +}) +``` + +Now, in your `index.js`: + +```js +import { Database } from '@nozbe/watermelondb' +import SQLiteAdapter from '@nozbe/watermelondb/adapters/sqlite' + +import schema from './model/schema' +import migrations from './model/migrations' +// import Post from './model/Post' // ⬅️ You'll import your Models here + +// First, create the adapter to the underlying database: +const adapter = new SQLiteAdapter({ + schema, + // (You might want to comment it out for development purposes -- see Migrations documentation) + migrations, + // (optional database name or file system path) + // dbName: 'myapp', + // (recommended option, only works on iOS currently) + experimentalUseJSI: true, + // (optional, but you should implement this method) + onSetUpError: error => { + // Database failed to load -- offer the user to reload the app or log out + } +}) + +// Then, make a Watermelon database from it! +const database = new Database({ + adapter, + modelClasses: [ + // Post, // ⬅️ You'll add Models to Watermelon here + ], + actionsEnabled: true, +}) +``` + +The above will work on React Native (iOS/Android) and NodeJS. For the web, instead of `SQLiteAdapter` use `LokiJSAdapter`: + +```js +import LokiJSAdapter from '@nozbe/watermelondb/adapters/lokijs' + +const adapter = new LokiJSAdapter({ + schema, + // (You might want to comment it out for development purposes -- see Migrations documentation) + migrations, + useWebWorker: false, + useIncrementalIndexedDB: true, + // dbName: 'myapp', // optional db name + // Optional, but recommended event handlers: + onIndexedDBVersionChange: () => { + // database was deleted in another browser tab (user logged out), so we must make sure we delete + // it in this tab as well + if (checkIfUserIsLoggedIn()) { + window.location.reload() + } + }, + // (optional, but recommended) + onQuotaExceededError: (error) => { + // Browser ran out of disk space -- do something about it + }, + onSetUpError: (error) => { + // Database failed to load -- offer the user to reload the app or log out + }, + extraIncrementalIDBOptions: { + onDidOverwrite: () => { + // Called when this adapter is forced to overwrite contents of IndexedDB. + // This happens if there's another open tab of the same app that's making changes. + // You might use it as an opportunity to alert user to the potential loss of data + } + } +}) + +// The rest is the same! +``` + +* * * + +## Next steps + +➡️ After Watermelon is installed, [**define your app's schema**](./Schema.md)