Skip to content

Rewrite multi-tab support section per issue #546 #552

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
benitav merged 2 commits into from
Aug 4, 2026
Merged

Rewrite multi-tab support section per issue #546 #552

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
69f618e
Rewrite multi-tab support section per issue #546
benitav Aug 4, 2026
ad29975
Less reliable note
benitav Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 12 additions & 10 deletions client-sdks/reference/javascript-web.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -539,19 +539,15 @@ async function listVfsEntries() {
### Multiple Tab Support

<Warning>
* Multiple tab support is not currently available on Android.
* Full multi-tab support relies on shared web workers, which are disabled by default on Android, iOS, and Safari. On these platforms, the SDK falls back to a less reliable broadcast-based mechanism, as described below.
* For Safari, use the [`OPFSCoopSyncVFS`](/client-sdks/reference/javascript-web#sqlite-virtual-file-systems) virtual file system to ensure stable multi-tab functionality.
</Warning>

Using PowerSync between multiple tabs is supported on some web browsers. Multiple tab support relies on shared web workers for database and sync streaming operations. When enabled, a shared web worker named `shared-powersync-[dbFileName]` will be created.
Depending on the setup, the shared worker is responsible for:
Using PowerSync between multiple tabs is supported on most desktop browsers. Multiple tab support relies on shared web workers for database and sync operations. When enabled, the SDK creates a shared web worker named `shared-powersync-[dbFileName]`.

1. __Sync__: The shared sync worker connects directly to the PowerSync backend instance and applies changes to the database. Note that the shared sync worker will call the `fetchCredentials` and `uploadData` method of the latest opened available tab. Closing a tab will shift the latest tab to the previously opened one.
2. __Database operations__: When using an IndexedDB-based VFS, the SDK can open database connections in a shared worker to ensure writes to the database will instantly be available between tabs.
The shared sync worker connects to the PowerSync Service and applies changes to the database on behalf of all tabs. It calls the `fetchCredentials` and `uploadData` methods of the most recently opened tab. When that tab closes, the worker uses the previously opened tab instead. When using an IndexedDB-based VFS, the SDK can also open database connections in a shared worker so that writes made in one tab are instantly available in the others.

Currently, using the SDK in multiple tabs without enabling the [enableMultiTabs](https://github.com/powersync-ja/powersync-js/blob/ed5bb49b5a1dc579050304fab847feb8d09b45c7/packages/web/src/db/adapters/web-sql-flags.ts#L23) flag will spawn a standard web worker per tab for DB operations. These workers are safe to operate on the DB concurrently, however changes from one tab may not update watches on other tabs. Only one tab can sync from the PowerSync instance at a time. The sync status will not be shared between tabs, only the oldest tab will connect and display the latest sync status.

Support is enabled by default if available. This can be disabled as below:
Multi-tab support is enabled by default where available. You can disable it with the [`enableMultiTabs` flag](#available-flags):

```js
export const db = new PowerSyncDatabase({
Expand All @@ -563,6 +559,12 @@ export const db = new PowerSyncDatabase({
});
```

#### Behavior Without Shared Workers

When multi-tab support is disabled, whether explicitly or because the platform does not support it, each tab spawns a standard web worker for database operations. These workers can safely operate on the database concurrently. Only one tab connects and syncs at a time, and only that tab's `fetchCredentials` and `uploadData` methods are called.

The SDK still tries to share state across tabs using broadcast channels (since version 2.1.0 of the SDK): update notifications for watched queries, the sync status (fields like `hasSynced` and download progress), and sync stream subscriptions made in any tab. This is less reliable than shared workers, so updates may not reach every tab.

### 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.
Expand All @@ -587,7 +589,7 @@ export const db = new PowerSyncDatabase({

#### Available Flags
<ParamField path="database.enableMultiTabs">
default: `true`
default: `true` (`false` on Android, iOS, and Safari)

Enables support for multiple tabs using shared web workers. When enabled, multiple tabs can interact with the same database and sync data seamlessly.
</ParamField>
Expand Down Expand Up @@ -633,7 +635,7 @@ export const db = new PowerSyncDatabase({
});
```

When disabled, each tab will use independent workers, and changes in one tab will not automatically propagate to others.
When disabled, each tab uses independent workers. The SDK tries to share sync status and update notifications for watched queries across tabs, but this is less reliable than shared workers. See [Behavior Without Shared Workers](#behavior-without-shared-workers).

**Example 2: Verbose Debugging with Broadcast Logs**

Expand Down