edgebase_flutter

Flutter SDK for EdgeBase
Auth, database, realtime, rooms, storage, functions, analytics, and push for Flutter apps

Flutter · iOS · Android · Web · macOS · Realtime · Firebase Push

Quickstart · Flutter Docs · Authentication · Database Client SDK · Room Client SDK

edgebase_flutter is the main client SDK for Flutter applications.

Use it when your app needs:

email/password, OAuth, magic link, MFA, and anonymous auth
direct client-side database access through EdgeBase access rules
live updates with onSnapshot()
presence, signals, and shared state with rooms
storage uploads and file URLs
client-side function calls and analytics
push registration for Android and iOS with Firebase Messaging

If you need trusted server-side access with a Service Key, use edgebase_admin instead. If you only want lower-level table, storage, and HTTP primitives, use edgebase_core.

EdgeBase is the open-source edge-native BaaS that runs on Edge, Docker, and Node.js.

This package is one part of the wider EdgeBase platform. For the full platform, CLI, Admin Dashboard, server runtime, docs, and all public SDKs, see the main repository: edge-base/edgebase.

Beta: the package is already usable, but some APIs may still evolve before general availability.

Documentation Map

Use this README for the fast overview, then jump into the docs when you need more depth:

Quickstart Create a local EdgeBase project and connect your app
Flutter SDK Flutter-specific setup and usage patterns
Authentication Email/password, OAuth, MFA, sessions, and captcha
Database Client SDK Query and mutation patterns
Database Subscriptions Live queries with onSnapshot()
Room Client SDK Presence, room state, members, signals, and media-ready flows
Functions Client SDK Calling EdgeBase functions from Flutter clients
Analytics Client SDK Track client-side events
Push Client SDK Client push concepts and message flows

For AI Coding Assistants

If you are using an AI coding assistant, check llms.txt before generating code.

It captures the package boundaries, canonical examples, and Dart-specific API differences that are easy to get wrong, especially around auth streams, instanceId, storage signed URLs, and room APIs.

Installation

flutter pub add edgebase_flutter

Starting a brand new EdgeBase project?

npm create edgebase@latest my-app

That scaffold creates a local EdgeBase app you can connect to from Flutter during development.

Local Development Tip

http://localhost:8787 works in the browser on your dev machine, but mobile runtimes usually need a device-reachable address:

Android emulator: http://10.0.2.2:8787
iOS simulator: http://127.0.0.1:8787
Physical device: http://<your-lan-ip>:8787

If you are running Flutter Web in the browser on the same machine, http://localhost:8787 is fine.

Quick Start

import 'package:edgebase_flutter/edgebase_flutter.dart';

final client = ClientEdgeBase('http://10.0.2.2:8787');

await client.auth.signIn(
  SignInOptions(
    email: 'june@example.com',
    password: 'pass1234',
  ),
);

final posts = await client
    .db('app')
    .table('posts')
    .where('published', '==', true)
    .orderBy('createdAt', direction: 'desc')
    .limit(10)
    .getList();

final health = await client.functions.get('health');

print(posts.items);
print(health);

Core API

Once you create a client, these are the main surfaces you will use:

client.auth Sign up, sign in, sign out, OAuth, MFA, and auth state handling
client.db(namespace, instanceId: ...) Query tables, create records, update documents, and subscribe to live changes
client.storage Upload files and resolve bucket URLs
client.functions Call EdgeBase functions from the client
client.room(namespace, roomId) Join realtime rooms for presence, state sync, and signals
client.analytics Send analytics events from the client
client.push Register device tokens and listen for foreground push messages

Room Media Transport

Flutter now exposes the same top-level room media transport entrypoint as the web and React Native SDKs:

final room = client.room('calls', 'demo-room');
await room.join();

final transport = room.media.transport(
  const RoomMediaTransportOptions(
    provider: 'cloudflare_realtimekit',
  ),
);

await transport.connect({
  'name': 'June',
  'customParticipantId': 'flutter-june',
});

await transport.enableAudio();
final localVideoView = await transport.enableVideo();

Flutter currently supports these room media providers:

cloudflare_realtimekit Managed media sessions through Cloudflare RealtimeKit
p2p Direct peer-to-peer media with signaling over room.signals

Install the matching optional runtime dependencies alongside edgebase_flutter:

flutter pub add realtimekit_core
flutter pub add flutter_webrtc

Current host-app smoke builds have been verified on Web, macOS, Android, and an Apple Silicon iOS simulator via direct Xcode device build.

Additional integration notes:

Android host apps need Java 11+ compile options and core library desugaring enabled
when you use both realtimekit_core and flutter_webrtc, exclude the older com.github.davidliu:audioswitch dependency from the app to avoid duplicate classes
generic flutter build ios --simulator can still trip over universal simulator linking, but direct arm64 simulator builds through Xcode succeeded in the current smoke matrix

Example Android app-level configuration:

android {
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_11
    targetCompatibility = JavaVersion.VERSION_11
    isCoreLibraryDesugaringEnabled = true
  }
}

dependencies {
  coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4")
}

configurations.all {
  exclude(group = "com.github.davidliu", module = "audioswitch")
}

Email and password

await client.auth.signUp(
  SignUpOptions(
    email: 'june@example.com',
    password: 'pass1234',
    data: {'displayName': 'June'},
  ),
);

await client.auth.signIn(
  SignInOptions(
    email: 'june@example.com',
    password: 'pass1234',
  ),
);

client.auth.onAuthStateChange.listen((user) {
  print('auth changed: ${user?.id}');
});

Current user

final user = client.auth.currentUser;
if (user != null) {
  print(user.email);
}

Database Queries

final posts = client.db('app').table('posts');

final latest = await posts
    .where('published', '==', true)
    .orderBy('createdAt', direction: 'desc')
    .limit(20)
    .getList();

final created = await posts.insert({
  'title': 'Hello EdgeBase',
  'published': true,
});

await posts.doc(created['id'] as String).update({
  'title': 'Updated title',
});

For instance databases, pass the instance id explicitly:

client.db('workspace', instanceId: 'ws-123');
client.db('user', instanceId: 'user-123');

Database Live

onSnapshot() returns a stream, so it fits naturally into Flutter state and StreamBuilder flows.

final stream = client
    .db('app')
    .table('posts')
    .where('published', '==', true)
    .onSnapshot();

final sub = stream.listen((change) {
  print(change.changeType);
  print(change.data);
});

// Later:
await sub.cancel();

Rooms And Presence

final room = client.room('presence', 'lobby-1');
await room.join();

room.members.onSync((members) {
  print('online members: ${members.length}');
});

room.signals.on('wave', (payload, meta) {
  print('signal: $payload');
});

await room.members.setState({'status': 'active'});
await room.signals.send('wave', {'emoji': 'hi'}, {'includeSelf': true});

Remember to leave the room when the screen or feature is disposed:

room.leave();

Storage

final bytes = [1, 2, 3, 4];

await client.storage.bucket('uploads').upload(
  'hello.bin',
  bytes,
  contentType: 'application/octet-stream',
);

final url = client.storage.bucket('uploads').getUrl('hello.bin');
print(url);

Push Notifications

edgebase_flutter integrates with Firebase Messaging for native push flows.

import 'package:firebase_core/firebase_core.dart';

await Firebase.initializeApp();

await client.push.register(metadata: {
  'topic': 'news',
});

client.push.onMessage((message) {
  print(message['title']);
  print(message['body']);
});

Choose The Right Dart Package

Package	Use it for
`edgebase_flutter`	Flutter apps running on device or web
`edgebase_admin`	Trusted server-side Dart code with Service Key access
`edgebase_core`	Low-level table, storage, and HTTP primitives
`edgebase`	Umbrella package when you want a broader Dart entry point

License

MIT