Dart/Flutter Web Support (Beta)

Set up the PowerSync Flutter SDK for web with Chrome and WASM support.

Since version 1.9.0, web support for Flutter is in a beta release. It is functionally ready for production use, provided that you’ve tested your use cases.

Please see the Limitations detailed below.

Demo App

The easiest way to test Flutter Web support is to run the Supabase Todo-List demo app:

1. Clone the powersync.dart repo.
2. Run dart pub get and melos run prepare in the repo’s root
3. cd into the demos/supabase-todolist folder
4. If you haven’t yet: cp lib/app_config_template.dart lib/app_config.dart (optionally update this config with your own Supabase and PowerSync project details).
5. Run flutter run -d chrome

Installing PowerSync in Your Own Project

Install the latest version of the package, for example:

dart pub add powersync:'^2.0.0'

Additional Config

Assets

Web support requires sqlite3.wasm and worker (powersync_db.worker.js and powersync_sync.worker.js) assets to be served from the web application. They can be downloaded to the web directory by running the following command in your application’s root folder.

dart run powersync:setup_web

The same code is used for initializing native and web PowerSyncDatabase clients.

OPFS for Improved Performance

This SDK supports different storage modes of the SQLite database with varying levels of performance and compatibility:

• OPFS (Origin-Private File System): A fast and modern file system implementation, but not available on older browsers or Safari private browsing.
• IndexedDB: Highly compatible with different browsers, but performance is slow.

PowerSync will detect what features the current browser supports to pick the best option. Starting with version 2.2.0 of the PowerSync Dart/Flutter SDK, OPFS is used on all major browsers (Chrome, Firefox and Safari).

In older versions of the SDK, apps had to be served with special headers (Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy) to support OPFS on Safari. These headers can be removed in version 2.2.0 of the SDK.

After upgrading the SDK and removing these headers, existing OPFS databases in Safari continue to work. If you didn’t use those headers before, old Safari users with IndexedDB databases will keep using them (but new users opening your app for the first time will get a faster OPFS database). There is no data loss in either scenario.

Limitations

The API for Web is essentially the same as for native platforms, however, some features within PowerSyncDatabase clients are not available.

Imports

Flutter Web does not support importing directly from sqlite3.dart as it uses dart:ffi.

Change imports from:

import 'package:powersync/sqlite3.dart`;
// or
import 'package:sqlite3/sqlite3.dart`;

to:

import 'package:sqlite3/sqlite3_common.dart';

in code which needs to run on the Web platform. Isolated native-specific code can still import from sqlite3.dart.

Database Connections

Web database connections do not support concurrency. A single database connection is used. readLock and writeLock contexts do not implement checks for preventing writable queries in read connections and vice-versa.

Direct access to the synchronous CommonDatabase (sqlite.Database equivalent for web) connection is not available. computeWithDatabase is not available on web.