Merge remote-tracking branch 'origin' into document-vfs

Author: benitav

client-sdk-references/javascript-web/usage-examples.mdx

@@ -268,3 +268,129 @@ The [WASQLiteDBAdapter](https://powersync-ja.github.io/powersync-js/web-sdk/clas
 ```
 chrome://inspect/#workers
 ```
+
+## Using PowerSyncDatabase Flags
+
+This guide provides an overview of the customizable flags available for the `PowerSyncDatabase` in the JavaScript Web SDK. These flags allow you to enable or disable specific features to suit your application's requirements.
+
+### Configuring Flags
+
+You can configure flags during the initialization of the `PowerSyncDatabase`. Flags can be set using the `flags` property, which allows you to enable or disable specific functionalities.
+
+```javascript
+import { PowerSyncDatabase, resolveWebPowerSyncFlags, WebPowerSyncFlags } from '@powersync/web';
+import { AppSchema } from '@/library/powersync/AppSchema';
+
+// Define custom flags
+const customFlags: WebPowerSyncFlags = resolveWebPowerSyncFlags({
+  enableMultiTabs: true,
+  broadcastLogs: true,
+  disableSSRWarning: false,
+  ssrMode: false,
+  useWebWorker: true,
+});
+
+// Create the PowerSync database instance
+export const db = new PowerSyncDatabase({
+  schema: AppSchema,
+  database: {
+    dbFilename: 'example.db',
+  },
+  flags: customFlags,
+});
+```
+
+#### Available Flags
+<ParamField path="enableMultiTabs">
+    default: `true`
+
+    Enables support for multiple tabs using shared web workers. When enabled, multiple tabs can interact with the same database and sync data seamlessly.
+</ParamField>
+
+<ParamField path="broadcastLogs">
+    default: `false`
+
+    Enables the broadcasting of logs for debugging purposes. This flag helps monitor shared worker logs in a multi-tab environment.
+</ParamField>
+
+<ParamField path="disableSSRWarning">
+    default: `false`
+
+    Disables warnings when running in SSR (Server-Side Rendering) mode.
+</ParamField>
+
+<ParamField path="ssrMode">
+    default: `false`
+
+    Enables SSR mode. In this mode, only empty query results will be returned, and syncing with the backend is disabled.
+</ParamField>
+
+<ParamField path="useWebWorker">
+    default: `true`
+
+    Enables the use of web workers for database operations. Disabling this flag also disables multi-tab support.
+</ParamField>
+
+
+### Flag Behavior
+
+#### Example 1: Multi-Tab Support
+
+By default, multi-tab support is enabled if supported by the browser. To explicitly disable this feature:
+
+```javascript
+export const db = new PowerSyncDatabase({
+  schema: AppSchema,
+  database: {
+    dbFilename: 'my_app_db.sqlite',
+  },
+  flags: {
+    enableMultiTabs: false,
+  },
+});
+```
+
+When disabled, each tab will use independent workers, and changes in one tab will not automatically propagate to others.
+
+#### Example 2: SSR Mode
+
+To enable SSR mode and suppress warnings:
+
+```javascript
+export const db = new PowerSyncDatabase({
+  schema: AppSchema,
+  database: {
+    dbFilename: 'my_app_db.sqlite',
+  },
+  flags: {
+    ssrMode: true,
+    disableSSRWarning: true,
+  },
+});
+```
+
+#### Example 3: Verbose Debugging with Broadcast Logs
+
+To enable detailed logging for debugging:
+
+```javascript
+export const db = new PowerSyncDatabase({
+  schema: AppSchema,
+  database: {
+    dbFilename: 'my_app_db.sqlite',
+  },
+  flags: {
+    broadcastLogs: true,
+  },
+});
+```
+
+Logs will include detailed insights into database operations and synchronization.
+
+### Recommendations
+
+1. **Set `enableMultiTabs`** to `true` if your application requires seamless data sharing across multiple tabs.
+2. **Set `useWebWorker`** to `true` for efficient database operations using web workers.
+3. **Set `broadcastLogs`** to `true` during development to troubleshoot and monitor database and sync operations.
+4. **Set `disableSSRWarning`** to `true` when running in SSR mode to avoid unnecessary console warnings.
+5. **Test combinations** of flags to validate their behavior in your application's specific use case.

client-sdk-references/kotlin-multiplatform.mdx

@@ -9,7 +9,7 @@ sidebarTitle: Overview
   </Card>
   <Card title="Source Code" icon="github" href="https://github.com/powersync-ja/powersync-kotlin/">
   Refer to the powersync-kotlin repo on GitHub.
-  </Card>  
+  </Card>
   <Card title="API Reference (Coming soon)" icon="book" href="">
   A full API Reference for this SDK is not yet available. This is planned for the stable release.
   </Card>
@@ -19,7 +19,7 @@ sidebarTitle: Overview
 </CardGroup>
 
 <Note>
-  The PowerSync Swift SDK is currently in a beta release. It is suitable for production use at this stage given you've tested your use cases extensively. Breaking changes are unlikely to occur.
+  This SDK is currently in a [**beta** release](/resources/feature-status). It is suitable for production use provided you've tested your specific use cases.
 </Note>
 
 ### SDK Features
@@ -31,12 +31,18 @@ sidebarTitle: Overview
 * Enables subscription to queries for receiving live updates.
 * Eliminates the need for client-side database migrations as these are managed automatically.
 
-Supported targets: Android and iOS.
+Supported targets: Android, iOS and Desktop.
 
 ## Installation
 
 See the [SDK's README](https://github.com/powersync-ja/powersync-kotlin?tab=readme-ov-file#installation) for installation instructions.
 
+<Info>
+    **JVM compatibility for Desktop**
+    * The following platforms are supported: Linux AArch64, Linux X64, MacOS AArch64, MacOS X64, Windows X64.
+    * See this [example build.gradle file](https://github.com/powersync-ja/powersync-kotlin/blob/main/demos/hello-powersync/composeApp/build.gradle.kts) for the relevant JVM config.
+</Info>
+
 ## Getting Started
 
 Before implementing the PowerSync SDK in your project, make sure you have completed these steps:
@@ -112,7 +118,7 @@ import com.powersync.PowerSyncDatabase
 
 // Android
 val driverFactory = DatabaseDriverFactory(this)
-// iOS
+// iOS & Desktop
 val driverFactory = DatabaseDriverFactory()
 ```
 

client-sdk-references/react-native-and-expo/react-native-web-support.mdx

@@ -7,36 +7,34 @@ title: "React Native Web Support"
 Support for React Native Web is available since versions 1.12.1 of the [PowerSync React Native SDK](/client-sdk-references/react-native-and-expo) and 1.8.0 if the [JavaScript/Web SDK](/client-sdk-references/javascript-web), and is currently in a **beta** release.
 
 A demo app showcasing this functionality is available here:
-<Card
-  title="powersync-js/demos/react-native-web-supabase-todolist"
-  icon="github"
-  href="https://github.com/powersync-ja/powersync-js/tree/main/demos/react-native-web-supabase-todolist"
-  horizontal
-/>
+
+<Card title="powersync-js/demos/react-native-web-supabase-todolist" icon="github" href="https://github.com/powersync-ja/powersync-js/tree/main/demos/react-native-web-supabase-todolist" horizontal />
 
 ## Configuring PowerSync in your React Native for Web project
 
 To ensure that PowerSync features are fully supported in your React Native Web project, follow the below steps. This documentation covers necessary web worker configurations, database instantiation, and multi-platform implementations.
 
-### 1\. Install Web SDK
+### 1. Install Web SDK
 
 The [PowerSync Web SDK](/client-sdk-references/javascript-web), alongside the [PowerSync React Native SDK](/client-sdk-references/react-native-and-expo), is required for Web support.
 
 See installation instructions [here](https://www.npmjs.com/package/@powersync/web).
 
-### 2\. Configure Web Workers
+### 2. Configure Web Workers
 
 For React Native for Web, workers need to be configured when instantiating `PowerSyncDatabase`. An example of this is available [here](https://github.com/powersync-ja/powersync-js/blob/main/demos/react-native-web-supabase-todolist/library/powersync/system.ts).
 
 To do this, copy the contents of `node_modules/@powersync/web/dist` to the root of your project (typically in the `public `directory). To make it easier to manage these files in the `public` directory, it is recommended to place the contents in a nested directory like `@powersync`.
 
-You can run the following bash command to automate the copying process. It will create copy the contents to `/public/@powersync`.
+The [`@powersync/web`](https://github.com/powersync-ja/powersync-js/tree/main/packages/web) package includes a CLI utility which can copy the required assets to the `public` directory (configurable with the `--output` option).
 
 ```bash
-mkdir -p public/@powersync && cp -r node_modules/@powersync/web/dist/* public/@powersync/
+# Places assets into public/@powersync by default. Override with `--output path/from_current_working_dir`.
+npx powersync-web copy-assets
+# or pnpm powersync-web copy-assets
 ```
 
-### 3\. Instantiate Web Workers
+### 3. Instantiate Web Workers
 
 The example below demonstrates how to instantiate the workers (PowerSync requires a database and a sync worker) when instantiating `PowerSyncDatabase`. You can either specify a path to the worker (they are available in the `worker` directory of the `dist` contents), or provide a factory function to create the worker.
 
@@ -82,7 +80,7 @@ this.powersync = new PowerSyncDatabaseWeb({
 
 This `PowerSyncDatabaseWeb` database will be used alongside the native `PowerSyncDatabase` to support platform-specific implementations. See the [Instantiating PowerSync](/client-sdk-references/react-native-and-expo/react-native-web-support#implementations) section below for more details.
 
-### 4\. Enable multiple platforms
+### 4. Enable multiple platforms
 
 To target both mobile and web platforms, you need to adjust the Metro configuration and handle platform-specific libraries accordingly.
 
@@ -192,6 +190,7 @@ export async function prompt(
 ```
 
 Which can then be used agnostically in a component.
+
 ```js
 import { Button } from 'react-native';
 import { prompt } from 'util/prompt';
@@ -214,15 +213,17 @@ import { prompt } from 'util/prompt';
   }}
 />;
 ```
-### 5\. Configure UMD target
+
+### 5. Configure UMD target
 
 React Native Web requires the UMD target of `@powersync/web` (available at `@powersync/web/umd`). To fully support this target version, configure the following in your project:
 
 1. Add `config.resolver.unstable_enablePackageExports = true;` to your `metro.config.js` file.
+
 2. TypeScript projects: In the `tsconfig.json` file specify the `moduleResolution` to be `Bundler`.
 
 ```json
  "compilerOptions": {
     "moduleResolution": "Bundler"
   }
-```
+```

client-sdk-references/swift.mdx

@@ -16,7 +16,7 @@ sidebarTitle: "Overview"
 </CardGroup>
 
 <Note>
-  The PowerSync Swift SDK is currently in a beta release. It is suitable for production use at this stage given you've tested your use cases extensively. Breaking changes are unlikely to occur.
+  This SDK is currently in a [**beta** release](/resources/feature-status). It is suitable for production use provided you've tested your specific use cases.
 </Note>
 
 ## Kotlin Multiplatform -> Native Swift SDK
@@ -26,7 +26,7 @@ The PowerSync Swift SDK currently makes use of the [PowerSync Kotlin Multiplatfo
 <Tip>
   **Demo App**
 
-  We recommend the [Supabase Todo List Demo](https://github.com/powersync-ja/powersync-swift/tree/main/Demo) app as a starting point for using the Swift SDK. See the README for details to run it.
+  We recommend the [Supabase To-Do List Demo](https://github.com/powersync-ja/powersync-swift/tree/main/Demo) app as a starting point for using the Swift SDK. See the README for details to run it.
 </Tip>
 
 ### SDK Features
@@ -90,7 +90,7 @@ The beta version of this SDK introduces a Swift-native wrapper around the packag
 * `@MainThread` usage is no longer required and should be removed.
 * Implementing `SuspendTaskWrapper` for database transactions is no longer required and should be removed.
 
-See the [Todo List Demo app](https://github.com/powersync-ja/powersync-swift/tree/main/Demo) as a reference.
+See the [To-Do List Demo app](https://github.com/powersync-ja/powersync-swift/tree/main/Demo) as a reference.
 
 ## Getting Started