diff --git a/resources/demo-apps-example-projects.mdx b/resources/demo-apps-example-projects.mdx index 75d31aa1..46e44234 100644 --- a/resources/demo-apps-example-projects.mdx +++ b/resources/demo-apps-example-projects.mdx @@ -1,148 +1,170 @@ --- -title: "Demo Apps / Example Projects" -description: "Gallery of example projects built with PowerSync." +title: "Demo Apps & Example Projects" +description: "Gallery of projects showcasing PowerSync implementations across platforms and frameworks." --- -Example projects are listed under backend they use, but you can easily wire up your own backend as documented [here](/installation/app-backend-setup). +This page showcases example projects organized by platform and backend technology. You can adapt any example to work with your preferred backend as documented in our [Backend Setup Guide](/installation/app-backend-setup). - We're constantly expanding our list of example projects. If you'd like to see an example that is not currently available, [let us know on Discord](https://discord.gg/powersync). + We continuously expand our collection of example projects. If you need an example that isn't available yet, [let us know on Discord](https://discord.gg/powersync). - - #### Supabase Backend: + #### Supabase Backend * [To-Do List App](https://github.com/powersync-ja/powersync.dart/tree/master/demos/supabase-todolist) - * Includes [Full-Text Search](/usage/use-case-examples/full-text-search) (FTS) example - * Includes example of [Handling Attachments](/integration-guides/supabase-+-powersync/handling-attachments) (files) - * [To-Do List app + Drift](https://github.com/powersync-ja/powersync.dart/tree/master/demos/supabase-todolist-drift) - * [To-Do List app demonstrating data persistence with local-only tables](https://github.com/powersync-ja/powersync.dart/tree/main/demos/supabase-todolist-optional-sync) + * Includes [Full-Text Search](/usage/use-case-examples/full-text-search) capabilities + * Demonstrates [File/Attachment Handling](/integration-guides/supabase-+-powersync/handling-attachments) + * [To-Do List App + Drift](https://github.com/powersync-ja/powersync.dart/tree/master/demos/supabase-todolist-drift) + * [To-Do List App with Local-Only Tables](https://github.com/powersync-ja/powersync.dart/tree/main/demos/supabase-todolist-optional-sync) - Shows data persistence without syncing * [Simple Chat App](https://github.com/powersync-ja/powersync.dart/tree/master/demos/supabase-simple-chat) * [Trello Clone App](https://github.com/powersync-ja/powersync-supabase-flutter-trello-demo) - #### Node.js Custom Backend: - * [To-Do List App](https://github.com/powersync-ja/powersync.dart/tree/main/demos/firebase-nodejs-todolist) - * Corresponding backend demo: [Node.js Backend for To-Do List App, with Firebase Auth](https://github.com/powersync-ja/powersync-nodejs-firebase-backend-todolist-demo) (also linked below) + #### Node.js Custom Backend + + * [To-Do List App with Firebase Auth](https://github.com/powersync-ja/powersync.dart/tree/main/demos/firebase-nodejs-todolist) + * Corresponding backend: [Node.js Backend with Firebase Auth](https://github.com/powersync-ja/powersync-nodejs-firebase-backend-todolist-demo) + + #### Rails Custom Backend - #### Rails Custom Backend: * [GoToFun App](https://github.com/powersync-ja/powersync-rails-flutter-demo) - * This repo includes both the Flutter app and Rails backend + * This repo contains both the Flutter app and Rails backend + + #### Django Custom Backend - #### Django Custom Backend: * [To-Do List App](https://github.com/powersync-ja/powersync.dart/tree/master/demos/django-todolist) - * Corresponding backend demo: [Django Backend for To-Do List App](https://github.com/powersync-ja/powersync-django-backend-todolist-demo) (also linked below) + * Corresponding backend: [Django Backend](https://github.com/powersync-ja/powersync-django-backend-todolist-demo) - #### Supabase Backend: + #### Supabase Backend + * [To-Do List App](https://github.com/powersync-ja/powersync-js/tree/main/demos/react-native-supabase-todolist) - * Includes an example of [Handling Attachments](/integration-guides/supabase-+-powersync/handling-attachments) (files) + * Demonstrates [File/Attachment Handling](/integration-guides/supabase-+-powersync/handling-attachments) * [PowerChat - Group Chat App](https://github.com/powersync-ja/powersync-js/tree/main/demos/react-native-supabase-group-chat) - #### Django Custom Backend: + #### Django Custom Backend + * [To-Do List App](https://github.com/powersync-ja/powersync-js/tree/main/demos/django-react-native-todolist) - * Corresponding backend demo: [Django Backend for To-Do List App](https://github.com/powersync-ja/powersync-django-backend-todolist-demo) (also linked below) + * Corresponding backend: [Django Backend](https://github.com/powersync-ja/powersync-django-backend-todolist-demo) - #### Supabase Backend: + #### Supabase Backend + * [React To-Do List App](https://github.com/powersync-ja/powersync-js/tree/main/demos/react-supabase-todolist) - * Includes [Full-Text Search](/usage/use-case-examples/full-text-search) (FTS) example - * [React To-Do List app demonstrating data persistence with local-only tables](https://github.com/powersync-ja/powersync-js/tree/main/demos/react-supabase-todolist-optional-sync) - * [React 'Multi-Client Widget'](https://github.com/powersync-ja/powersync-js/tree/main/demos/react-multi-client) - * This is the demo widget displayed on the [PowerSync homepage](https://www.powersync.com/) which shows how data flows from one PowerSync client to another. + * Includes [Full-Text Search](/usage/use-case-examples/full-text-search) capabilities + * [React To-Do List App with Local-Only Tables](https://github.com/powersync-ja/powersync-js/tree/main/demos/react-supabase-todolist-optional-sync) - Shows data persistence without syncing + * [React Multi-Client Widget](https://github.com/powersync-ja/powersync-js/tree/main/demos/react-multi-client) + * Featured on the [PowerSync homepage](https://www.powersync.com/) demonstrating real-time data flow between clients * [Vue To-Do List App](https://github.com/powersync-ja/powersync-js/tree/main/demos/vue-supabase-todolist) * [Angular To-Do List App](https://github.com/powersync-ja/powersync-js/tree/main/demos/angular-supabase-todolist) * [Yjs CRDT Text Collaboration Demo](https://github.com/powersync-ja/powersync-js/tree/main/demos/yjs-react-supabase-text-collab) - #### Starter Projects: - * [example-electron](https://github.com/powersync-ja/powersync-js/tree/main/demos/example-electron): Example demonstrating the use of PowerSync together with an [Electron](https://www.electronjs.org/) rendered web app. Also see the [Node.js + Electron example](https://github.com/powersync-ja/powersync-js/tree/main/demos/example-electron-node) which runs PowerSync in the main process. - * [example-capacitor](https://github.com/powersync-ja/powersync-js/tree/main/demos/example-capacitor): Example demonstrating the use of PowerSync together with a [Capacitor](https://capacitorjs.com/) app. - * [example-nextjs](https://github.com/powersync-ja/powersync-js/blob/main/demos/example-nextjs/README.md): A minimal example demonstrating setup with [Next.js](https://nextjs.org/). - * [example-webpack](https://github.com/powersync-ja/powersync-js/blob/main/demos/example-webpack/README.md): A minimal example demonstrating bundling with [Webpack](https://webpack.js.org/). - * [example-vite](https://github.com/powersync-ja/powersync-js/blob/main/demos/example-vite/README.md): A minimal example demonstrating bundling with [Vite](https://vitejs.dev/). + #### Framework Integration Examples - #### Other - * [example-vite-encryption](https://github.com/powersync-ja/powersync-js/blob/main/demos/example-vite-encryption/README.md): A minimal example demonstrating encryption of the web database. + * [Electron](https://github.com/powersync-ja/powersync-js/tree/main/demos/example-electron) - PowerSync in an Electron web app (renderer process) + * Also see [Node.js + Electron](https://github.com/powersync-ja/powersync-js/tree/main/demos/example-electron-node) for PowerSync in the main process + * [Capacitor](https://github.com/powersync-ja/powersync-js/tree/main/demos/example-capacitor) - PowerSync in a Capacitor app + * [Next.js](https://github.com/powersync-ja/powersync-js/blob/main/demos/example-nextjs/README.md) - Minimal setup with Next.js + * [Webpack](https://github.com/powersync-ja/powersync-js/blob/main/demos/example-webpack/README.md) - Bundling with Webpack + * [Vite](https://github.com/powersync-ja/powersync-js/blob/main/demos/example-vite/README.md) - Bundling with Vite + * [Vite with Encryption](https://github.com/powersync-ja/powersync-js/blob/main/demos/example-vite-encryption/README.md) - Web database encryption demo - #### Self-Hosted: - * [CLI example](https://github.com/powersync-ja/powersync-js/tree/main/demos/example-node): Demonstrates a small Node.js CLI client opening a database, connecting PowerSync and running live queries. + #### Examples - #### Other - * [Electron](https://github.com/powersync-ja/powersync-js/tree/main/demos/example-electron-node): An Electron example that runs PowerSync in the main process using the Node.js SDK. As opposed to [this Electron example](https://github.com/powersync-ja/powersync-js/tree/main/demos/example-electron) running PowerSync in the renderer process using the Web SDK. + * [CLI Example](https://github.com/powersync-ja/powersync-js/tree/main/demos/example-node) - Node.js CLI client connecting to PowerSync and running live queries + * [Electron Main Process](https://github.com/powersync-ja/powersync-js/tree/main/demos/example-electron-node) - PowerSync in Electron's main process using the Node.js SDK - #### Supabase Backend: + #### Supabase Backend - * [Minimal 'Hello PowerSync' App](https://github.com/powersync-ja/powersync-kotlin/tree/main/demos/hello-powersync) - * Includes Android, iOS and Desktop (JVM) targets. + * [Hello PowerSync](https://github.com/powersync-ja/powersync-kotlin/tree/main/demos/hello-powersync) - Minimal starter app + * Supports Android, iOS, and Desktop (JVM) targets * [To-Do List App](https://github.com/powersync-ja/powersync-kotlin/tree/main/demos/supabase-todolist) - * Includes Android, iOS targets. - * [To-Do List App as a native Android application](https://github.com/powersync-ja/powersync-kotlin/tree/main/demos/android-supabase-todolist) - + * Supports Android and iOS targets + * Includes a guide for [implementing background sync on Android](https://github.com/powersync-ja/powersync-kotlin/blob/main/demos/supabase-todolist/docs/BackgroundSync.md) + * [Native Android To-Do List App](https://github.com/powersync-ja/powersync-kotlin/tree/main/demos/android-supabase-todolist) - #### Supabase Backend: + #### Supabase Backend + * [To-Do List App](https://github.com/powersync-ja/powersync-swift/tree/main/Demo) - - #### Self-Hosted: - * [CLI example](https://github.com/powersync-ja/powersync-dotnet/tree/main/demos/CommandLine) + #### Examples + + * [CLI Application](https://github.com/powersync-ja/powersync-dotnet/tree/main/demos/CommandLine) - + + #### Django + * [Django Backend for To-Do List App](https://github.com/powersync-ja/powersync-django-backend-todolist-demo) - * Corresponding front-end demo app: React Native [To-Do List App](https://github.com/powersync-ja/powersync-js/tree/main/demos/django-react-native-todolist) (also linked above) - * [Node.js Backend for To-Do List App ](https://github.com/powersync-ja/powersync-nodejs-backend-todolist-demo) - * [Node.js Backend for To-Do List App, with Firebase Auth](https://github.com/powersync-ja/powersync-nodejs-firebase-backend-todolist-demo) - * Corresponding front-end demo app: Flutter [To-Do List App](https://github.com/powersync-ja/powersync.dart/tree/main/demos/firebase-nodejs-todolist) (also linked above) + * For use with: + * React Native [To-Do List App](https://github.com/powersync-ja/powersync-js/tree/main/demos/django-react-native-todolist) + * Flutter [To-Do List App](https://github.com/powersync-ja/powersync.dart/tree/master/demos/django-todolist) + + #### Node.js + + * [Node.js Backend for To-Do List App](https://github.com/powersync-ja/powersync-nodejs-backend-todolist-demo) + * [Node.js Backend with Firebase Auth](https://github.com/powersync-ja/powersync-nodejs-firebase-backend-todolist-demo) + * For use with: Flutter [To-Do List App with Firebase Auth](https://github.com/powersync-ja/powersync.dart/tree/main/demos/firebase-nodejs-todolist) + + #### Rails + * [Rails Backend for GoToFun App](https://github.com/powersync-ja/powersync-rails-flutter-demo/tree/main/gotofun-backend) - * Corresponding front-end demo app: Flutter [GoToFun App](https://github.com/powersync-ja/powersync-rails-flutter-demo/tree/main/gotofun-app) (also linked above) + * For use with: Flutter [GoToFun App](https://github.com/powersync-ja/powersync-rails-flutter-demo/tree/main/gotofun-app) - - * [To-Do List App with Docker Compose](https://github.com/powersync-ja/self-host-demo) - * [Postgres + Node.js Backend](https://github.com/powersync-ja/self-host-demo/tree/main/demos/nodejs-postgres-bucket-storage) - * [Postgres + Postgres sync bucket storage + Node.js Backend](https://github.com/powersync-ja/self-host-demo/tree/main/demos/nodejs) - * [MongoDB + Node.js Backend](https://github.com/powersync-ja/self-host-demo/tree/main/demos/nodejs-mongodb) - * [MySQL + Node.js Backend](https://github.com/powersync-ja/self-host-demo/tree/main/demos/nodejs-mysql) - * [Supabase Backend (Postgres) + Local Development Example](https://github.com/powersync-ja/self-host-demo/tree/main/demos/supabase) - * [Django Backend](https://github.com/powersync-ja/self-host-demo/tree/main/demos/django) + + #### Complete Stacks with Docker Compose + + * [To-Do List App with Docker Compose](https://github.com/powersync-ja/self-host-demo) - Various backend configurations: + * [Postgres + Node.js](https://github.com/powersync-ja/self-host-demo/tree/main/demos/nodejs-postgres-bucket-storage) + * [Postgres + Postgres Sync Bucket Storage + Node.js](https://github.com/powersync-ja/self-host-demo/tree/main/demos/nodejs) + * [MongoDB + Node.js](https://github.com/powersync-ja/self-host-demo/tree/main/demos/nodejs-mongodb) + * [MySQL + Node.js](https://github.com/powersync-ja/self-host-demo/tree/main/demos/nodejs-mysql) + * [Supabase (Postgres) + Local Development](https://github.com/powersync-ja/self-host-demo/tree/main/demos/supabase) + * [Django](https://github.com/powersync-ja/self-host-demo/tree/main/demos/django) - #### Flutter: + #### Custom Backends + + * Laravel Backend + * https://github.com/IsmailAshour/powersync-laravel-backend + + #### Flutter Projects - * Flutter + Supabase + Firebase - * [https://github.com/Gambley1/flutter-instagram-offline-first-clone](https://github.com/Gambley1/flutter-instagram-offline-first-clone) - * Testing PowerSync with Jepsen for formal consistency validation - * [https://github.com/nurturenature/jepsen-powersync](https://github.com/nurturenature/jepsen-powersync) + * Flutter Instagram Clone with Supabase + Firebase + * https://github.com/Gambley1/flutter-instagram-offline-first-clone + * Jepsen PowerSync Testing - Formal consistency validation framework + * https://github.com/nurturenature/jepsen-powersync - #### JavaScript & TypeScript: + #### JavaScript & TypeScript Projects - * SolidJS hooks for PowerSync queries - * [https://github.com/aboviq/powersync-solid](https://github.com/aboviq/powersync-solid) - * Effect + Kysely + Stytch - * [https://github.com/guillempuche/localfirst\_react\_server](https://github.com/guillempuche/localfirst_react_server) + * SolidJS Hooks for PowerSync Queries + * https://github.com/aboviq/powersync-solid + * Effect + Kysely + Stytch Integration + * https://github.com/guillempuche/localfirst_react_server * Tauri + Shadcn UI - * [https://github.com/romatallinn/powersync-tauri](https://github.com/romatallinn/powersync-tauri) - * Expo Web - * [https://github.com/ImSingee/powersync-web-workers](https://github.com/ImSingee/powersync-web-workers) - * Our [React Native Web](/client-sdk-references/react-native-and-expo/react-native-web-support) support should now remove the need to "Patch the `@powersync/web` module" + * https://github.com/romatallinn/powersync-tauri + * Expo Web Integration + * https://github.com/ImSingee/powersync-web-workers + * Note: Our [React Native Web support](/client-sdk-references/react-native-and-expo/react-native-web-support) now eliminates the need to patch the `@powersync/web` module ## Additional Resources -A growing collection of use case examples and tutorials are also available: +Also explore our growing collection of use case examples and tutorials: diff --git a/snippets/node/installation.mdx b/snippets/node/installation.mdx index d453fbe5..ba318980 100644 --- a/snippets/node/installation.mdx +++ b/snippets/node/installation.mdx @@ -42,4 +42,10 @@ This SDK requires [`better-sqlite3`](https://www.npmjs.com/package/better-sqlite pnpm install better-sqlite3 ``` - \ No newline at end of file + + +**Common installation issues** + +The `better-sqlite` package requires native compilation, which depends on certain system tools. This compilation process is handled by `node-gyp` and may fail if required dependencies are missing or misconfigured. + +Refer to the [PowerSync Node package README](https://www.npmjs.com/package/@powersync/node) for more details. \ No newline at end of file diff --git a/usage/use-case-examples/background-syncing.mdx b/usage/use-case-examples/background-syncing.mdx index f3d7d1c4..99fca960 100644 --- a/usage/use-case-examples/background-syncing.mdx +++ b/usage/use-case-examples/background-syncing.mdx @@ -1,49 +1,70 @@ --- title: "Background Syncing" -description: "You might want to run PowerSync operations while the client device is inactive or the app is in the background." +description: "Run PowerSync operations while your app is inactive or in the background" --- -## Flutter +# Background Syncing -We have done an initial investigation into how background syncing could be accomplished by using Flutter with [workmanager](https://github.com/fluttercommunity/flutter_workmanager/). However, the flow for other frameworks (e.g. React Native) should be quite similar using an equivalent package. Please reach out on our [Discord](https://discord.gg/powersync) for more assistance. +Applications often need to sync data when they're not in active use. This document explains background syncing implementations with PowerSync. -### Guide +## Platform Support -We assume you have followed the platform setup guide in the [workmanager README](https://github.com/fluttercommunity/flutter_workmanager/#platform-setup). Note we are running this in the context of our [Supabase To-Do List Demo](https://github.com/powersync-ja/powersync.dart/tree/main/demos/supabase-todolist) app. +Background syncing has been tested in: + +- **Flutter** - Using [workmanager](https://github.com/fluttercommunity/flutter_workmanager/) +- **Kotlin Multiplatform - Android** - Implementation details in the [Supabase To-Do List demo](https://github.com/powersync-ja/powersync-kotlin/blob/main/demos/supabase-todolist/docs/BackgroundSync.md) + +These examples can be adapted for other frameworks like React Native. For implementation questions or assistance, chat to us on [Discord](https://discord.gg/powersync). + +## Flutter Implementation Guide + +### Prerequisites + +1. Complete the [workmanager platform setup](https://github.com/fluttercommunity/flutter_workmanager/#platform-setup) +2. Review the [Supabase To-Do List Demo](https://github.com/powersync-ja/powersync.dart/tree/main/demos/supabase-todolist) for context + +### Configure the Background Task In `main.dart`: ```dart void main() async { - ... + // ... existing setup code ... + const simpleTaskKey = "com.domain.myapp.taskId"; + // Mandatory if the App is obfuscated or using Flutter 3.1+ @pragma('vm:entry-point') void callbackDispatcher() { Workmanager().executeTask((task, inputData) async { switch (task) { case simpleTaskKey: + // Initialize PowerSync database and connection final currentConnector = await openDatabase(); db.connect(connector: currentConnector!); - await TodoList.create('testing1234'); + + // Perform database operations + await TodoList.create('New background task item'); await currentConnector.uploadData(db); await TodoList.create('testing1111'); await currentConnector.uploadData(db); // print("$simpleTaskKey was executed. inputData = $inputData"); break; } + // Close database when done await db.close(); return Future.value(true); }); } + // Initialize the workmanager with your callback Workmanager().initialize( callbackDispatcher, - // If enabled it will post a notification whenever the task is running. Handy for debugging tasks + // Shows notifications during task execution (useful for debugging) isInDebugMode: true ); - - ... + + // ... rest of your app initialization ... } ``` @@ -65,7 +86,9 @@ await currentConnector.uploadData(db); 2. Run a write (in the case of this demo app, we create a 'todo list') 3. Make sure to run `currentConnector.uploadData(db);` so that the local write is uploaded to the remote database. -Create a way to test this, e.g. by using a button: +### Testing + +Add a test button: ```dart ElevatedButton( @@ -85,12 +108,16 @@ Create a way to test this, e.g. by using a button: ), ``` -Put your app in the background and wait 10 seconds, then check your remote database and it should have the new record. +Press the button, background the app, wait 10 seconds, then verify new records in the remote database. -### Android +### Platform Compatibility -This worked with Android. +#### Android +- Implementation works as expected. -### iOS +#### iOS +- At the time of writing (January 2024), we were only able to get part of this to work using the branch for [this PR](https://github.com/fluttercommunity/ +flutter_workmanager/pull/511) into workmanager. +- While testing we were not able to get iOS background fetching to work, however this is most likely an +[issue](https://github.com/fluttercommunity/flutter_workmanager/issues/515) with the package. -At the time of writing (January 2024), we were only able to get part of this to work using the branch for [this PR](https://github.com/fluttercommunity/flutter_workmanager/pull/511) into workmanager. While testing we were not able to get iOS background fetching to work, however this is most likely an [issue](https://github.com/fluttercommunity/flutter_workmanager/issues/515) with the package.