flutter_module_bridge library

flutter_module_bridge — A production-grade, bidirectional communication bridge between Flutter modules and native Android/iOS applications.

Quick Start

// Initialize once, typically in main()
await NativeBridge.initialize(
  config: BridgeConfig(channelName: 'app_bridge'),
);

// Make a typed call
final user = await NativeBridge.call<LoginResponse>(
  'auth.login',
  LoginRequest(email: 'user@example.com', password: '••••'),
);

// Subscribe to native events
NativeBridge.on<UserUpdatedEvent>('userUpdated', (event) {
  print('User updated: ${event.name}');
});

// Stream continuous native data
NativeBridge.stream<LocationEvent>('location').listen((loc) {
  print('${loc.lat}, ${loc.lng}');
});

Architecture

The bridge is structured around four pillars:

See the architecture documentation for full details.

Classes

BackoffStrategy
Strategy for calculating delay between reconnection attempts.
BridgeBatchItem<T>
A single item in a BridgeInstance.batch call.
BridgeBatchResult
The result of a BridgeInstance.batch call.
BridgeCancellationToken
A token that allows a caller to cancel a pending bridge request.
BridgeCapabilities
The set of features that have been negotiated between Flutter and native during the BridgeHandshake phase.
BridgeCodec
Abstract contract for all payload codecs in the bridge.
BridgeConfig
Complete configuration for a BridgeInstance.
BridgeEnvelope
The universal message container for all Flutter↔Native communication.
BridgeEventBus
The bridge event bus — dispatches native events to typed Dart listeners.
BridgeEventSubscription<T>
Internal implementation of EventSubscription.
BridgeHandshakeAck
The acknowledgment native sends back in response to a BridgeHandshakeOffer.
BridgeHandshakeOffer
The offer Flutter sends to native at the start of a BridgeHandshake.
BridgeInstance
A named bridge instance managing a single Flutter↔Native channel.
BridgeLogger
Abstract interface for bridge logger implementations.
BridgeMetrics
A point-in-time snapshot of bridge runtime metrics.
BridgeMiddleware
Abstract interface for bridge middleware.
BridgePlugin
Abstract base class for all bridge plugins.
BridgePluginContext
Context passed to BridgePlugin.onInstall.
BridgeProgress
A progress snapshot for a long-running native operation.
BridgeProtocol
The Bridge Protocol — responsible for encoding, decoding, and validating all BridgeEnvelope messages exchanged across the transport boundary.
BridgeQueueConfig
Configuration for the pre-initialization request queue.
BridgeRequestContext
Context object passed through the middleware pipeline for each request.
BridgeRequestOptions
Per-request options that override the global BridgeConfig settings.
BridgeResponseContext
Context for a native response passing through the response middleware chain.
BridgeTransport
Abstract transport layer — moves BridgeEnvelope objects between Flutter and native without knowing anything about their contents.
ConsoleBridgeLogger
The default BridgeLogger — prints to debugPrint in debug mode only.
EventSubscription
A handle to an event subscription returned by BridgeInstance.on or BridgeInstance.once.
HeartbeatPlugin
Built-in plugin that sends periodic heartbeat pings to native.
JsonBridgeCodec
The default codec — encodes via toJson() / decodes via TypeRegistry.
LoggingMiddleware
Built-in middleware that logs every request, response, and error.
MockTransport
An in-memory transport for testing — no Flutter engine or platform required.
NamespacedBridge
A BridgeInstance proxy that automatically applies a namespace prefix to all method calls, event subscriptions, and event emissions.
NativeBridge
The top-level registry and entry point for flutter_module_bridge.
ReconnectionPlugin
Built-in plugin that automatically attempts to reconnect on connection loss.
RetryMiddleware
Built-in middleware that retries failed requests.
TypeAdapter<T>
A pair of functions that know how to serialize and deserialize type T.
TypeRegistry
A registry mapping Dart types to their TypeAdapters.

Enums

BridgeCapabilityKey
Enumeration of all negotiable bridge capabilities.
BridgeConnectionState
The observable connection state of a BridgeInstance.
BridgeMessageType
Discriminates every message exchanged across the Bridge Protocol.
BridgeProgressUnit
The unit of measurement for a BridgeProgress value.
QueueOverflowStrategy
Behaviour when the pre-initialization queue is full and a new request arrives.

Exceptions / Errors

BridgeCancelledException
Thrown when a request is cancelled via BridgeCancellationToken.
BridgeChannelException
Thrown when the underlying transport channel fails.
BridgeDecodeException
Thrown when decoding a native response into the expected Dart type fails.
BridgeDisposedException
Thrown when a method is called on a BridgeInstance that has been disposed.
BridgeEncodeException
Thrown when encoding a Dart object for transport fails.
BridgeException
Base class for every exception thrown by the bridge.
BridgeInitializationException
Thrown when NativeBridge.initialize fails or is called incorrectly.
BridgeNativeException
Thrown when the native handler throws an exception or returns an error.
BridgeNotFoundException
Thrown when no native handler is registered for the requested method.
BridgePermissionException
Thrown when a method call fails due to insufficient native permissions.
BridgeQueueFullException
Thrown when a request is submitted but the pre-initialization queue is full.
BridgeSerializationException
Thrown when serialization or deserialization fails.
BridgeTimeoutException
Thrown when a request or handshake exceeds its configured timeout.
BridgeUnknownException
Catch-all for unexpected errors that don't fit a more specific category.