Cindel on Flutter Web: SQLite, OPFS, and Browser Storage

Cindel runs in Flutter Web apps using the same typed API you use on native platforms. You open a database, register your generated schemas, and work through typed collections like db.todos — no code changes required when moving between native and web targets. The key difference is that the directory parameter becomes a logical browser database name rather than a filesystem path, and Cindel uses a SQLite/OPFS backend instead of MDBX, which is not available in browsers.

Required Dependencies

Add both cindel and cindel_flutter_libs to your pubspec.yaml. The cindel_flutter_libs package bundles the Web worker, JavaScript glue, and Wasm runtime that Cindel needs to run in the browser. Your Dart code only imports package:cindel/cindel.dart, but the browser needs everything cindel_flutter_libs ships.

dependencies:
  cindel: ^1.0.0
  cindel_flutter_libs: ^1.0.0  # bundles the Web worker, JS glue, and Wasm runtime
dev_dependencies:
  build_runner: ^2.15.0
  cindel_generator: ^1.0.0

Browser Requirements

Cindel Web requires the following browser features to be available:

Workers — used to run the database engine off the main thread
Wasm — the native Rust core is compiled to WebAssembly
OPFS — the Origin Private File System is where Cindel stores database files

All modern browsers support these features. If the browser, a privacy mode, or an embedded WebView blocks any of them, opening the database can fail. See Handling Storage Errors below.

MDBX is not used in browsers. Do not configure MDBX as a backend for Web targets — use the default SQLite/OPFS path.

Opening a Web Database

Pass a logical name to directory when calling Cindel.open. This name identifies the browser database; it is not a folder that appears on the user’s device.

// On web, directory is a logical name (not a file path)
final db = await Cindel.open(
  directory: 'myapp_production',
  schemas: [TodoSchema],
);

Once open, use your generated collections exactly as you would on native:

await db.todos.put(todo);

final saved = await db.todos.get(todo.dbId);
final all   = await db.todos.all().findAll();

In-Memory Databases for Tests

For unit tests or temporary work that should not persist between runs, use Cindel.openInMemory:

final db = await Cindel.openInMemory(schemas: [TodoSchema]);

Use stable, descriptive directory names for your production database (e.g. myapp_production) and separate names for demos, previews, or tests (e.g. myapp_demo, myapp_test) so they never share browser storage.

Supported APIs on Web

All of the following work the same on Web as they do on native:

Feature	Supported
`Cindel.open`	✅
`Cindel.openInMemory`	✅
Typed CRUD (`put`, `get`, `delete`, etc.)	✅
Typed queries	✅
Property projections and aggregates	✅
Query updates and deletes	✅
Read and write transactions	✅
`documentIdsPage` bounded scans	✅
Uncompressed JSONL backup import/export	✅
Sync config via `CindelSyncConfig`	✅
Typed object, collection, query, and lazy watchers	✅

Example: Query with Sorting

final newest = await db.todos
    .all()
    .sortByCreatedAt(order: CindelSortOrder.descending)
    .limit(20)
    .findAll();

Example: Collection Watcher

final sub = db.todos.watchCollection().listen((todos) {
  // Update your Web UI state here.
});

Backup on Web

Use CindelBackupCompression.none when exporting on Web. Gzip compression is not supported in the browser runtime.

await CindelBackup.exportDatabase(
  database: db,
  collections: [CindelBackupCollection(TodoSchema)],
  compression: CindelBackupCompression.none,
  output: output,
);

Current Limitations

Keep the following restrictions in mind when targeting Web:

No MDBX backend — only SQLite/OPFS is available in browsers.
Watcher delivery is single-tab only — this includes sync watchers. One tab cannot receive watcher events triggered by writes in another tab.
No multi-tab coordination — if your app supports multiple tabs, design the UI so each tab can reload or re-open its local view independently.
Browser storage quota and OPFS availability vary — quota limits and OPFS support depend on the browser, OS, and user settings.

Handling Storage Errors

If the browser blocks Workers, Wasm, or OPFS — for example in a private browsing session or when storage quota is exceeded — Cindel.open will throw a CindelOpenError.

Always wrap Cindel.open in a try/catch on Web and show a clear in-app message when storage is unavailable. Do not assume OPFS is available in all browsing contexts — private mode and certain mobile WebViews are common failure points.

try {
  final db = await Cindel.open(
    directory: 'myapp_production',
    schemas: [TodoSchema],
  );
} on CindelOpenError catch (e) {
  // Storage unavailable — show a user-facing message.
  showStorageUnavailableDialog(e);
}

Get Started

Data Modeling

Querying Data

Core Features

Platforms

Reference

Cindel on Flutter Web: SQLite, OPFS, and Browser Storage

Required Dependencies

Browser Requirements

Opening a Web Database

In-Memory Databases for Tests

Supported APIs on Web

Example: Query with Sorting

Example: Collection Watcher

Backup on Web

Current Limitations

Handling Storage Errors

​Required Dependencies

​Browser Requirements

​Opening a Web Database

​In-Memory Databases for Tests

​Supported APIs on Web

​Example: Query with Sorting

​Example: Collection Watcher

​Backup on Web

​Current Limitations

​Handling Storage Errors

Required Dependencies

Browser Requirements

Opening a Web Database

In-Memory Databases for Tests

Supported APIs on Web

Example: Query with Sorting

Example: Collection Watcher

Backup on Web

Current Limitations

Handling Storage Errors