Minor additions (#154)

* General wording and structure improvements

* common installation issues for node

* Update resources/demo-apps-example-projects.mdx

Author: benitav

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).
 
 <Check>
-  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).
 </Check>
 
-
 <AccordionGroup>
   <Accordion title="Flutter" icon="flutter">
-  #### 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)
   </Accordion>
 
   <Accordion title="React Native & Expo" icon="react">
-  #### 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)
   </Accordion>
 
   <Accordion title="JavaScript Web" icon="js">
-  #### 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
   </Accordion>
 
   <Accordion title="Node.js (alpha)" icon="node-js">
-  #### 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
   </Accordion>
 
   <Accordion title="Kotlin Multiplatform" icon="k">
-  #### 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)
   </Accordion>
 
   <Accordion title="Swift" icon="swift">
-  #### Supabase Backend:
+  #### Supabase Backend
+
   * [To-Do List App](https://github.com/powersync-ja/powersync-swift/tree/main/Demo)
-    
   </Accordion>
 
   <Accordion title=".NET (alpha)" icon="microsoft">
-  #### 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)
   </Accordion>
 
-  <Accordion title="Custom Backend Examples" icon="screwdriver-wrench">
+  <Accordion title="Backend Examples" icon="screwdriver-wrench">
+  #### 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)
   </Accordion>
 
-  <Accordion title="Self-Hosting" icon="desktop">
-  * [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)  
+  <Accordion title="Self-Hosting Examples" icon="desktop">
+  #### 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)  
   </Accordion>
 
   <Accordion title="Notable Community Projects" icon="people-carry-box">
-  #### 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
   </Accordion>
 </AccordionGroup>
 
 ## 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:
 
 <CardGroup>
   <Card title="Use Case Examples" icon="gear" href="/usage/use-case-examples" horizontal />

snippets/node/installation.mdx

@@ -42,4 +42,10 @@ This SDK requires [`better-sqlite3`](https://www.npmjs.com/package/better-sqlite
     pnpm install better-sqlite3
     ```
   </Tab>
-</Tabs>
+</Tabs>
+
+**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.