Qora
Flutter Integration

Setup

Install qora_flutter, create a QoraClient instance, and provide it to the widget tree with QoraScope.

Installation

Add qora_flutter to your pubspec.yaml:

pubspec.yaml
dependencies:
  qora_flutter: ^ 1.3.1

Then fetch:

flutter pub get
qora_flutter automatically includes qora and connectivity_plus as dependencies. You do not need to add them separately.

Create the Client

QoraClient is the central cache and request orchestrator. Create one instance per app (or per DI scope):

main.dart
import 'package:flutter/foundation.dart';
import 'package:qora_flutter/qora_flutter.dart';

final client = QoraClient(
  config: QoraClientConfig(
    defaultOptions: QoraOptions(
      staleTime: Duration(minutes: 5),
      gcTime: Duration(minutes: 10),
      retryCount: 3,
    ),
    debugMode: kDebugMode,
  ),
);
Set debugMode: kDebugMode to get detailed logs in development without any performance cost in production.

Wrap Your App with QoraScope

QoraScope is a StatefulWidget that exposes the client to every descendant via an internal InheritedWidget. Place it as close to the root as possible:

main.dart
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:qora_flutter/qora_flutter.dart';

void main() {
  final client = QoraClient(
    config: const QoraClientConfig(debugMode: kDebugMode),
  );

  runApp(
    QoraScope(
      client: client,
      child: const MyApp(),
    ),
  );
}

Any descendant widget can now access the client via context.qora or QoraScope.of(context).

Optional: Lifecycle and Connectivity Managers

For automatic refetch-on-resume and refetch-on-reconnect behavior, pass the built-in managers to QoraScope:

main.dart
void main() {
  final client = QoraClient();

  runApp(
    QoraScope(
      client: client,
      lifecycleManager: FlutterLifecycleManager(
        qoraClient: client,
        // Invalidate all queries if the app was backgrounded for more than 30 s
        minBackgroundDuration: const Duration(seconds: 30),
      ),
      connectivityManager: FlutterConnectivityManager(),
      child: const MyApp(),
    ),
  );
}
ManagerBehaviour
FlutterLifecycleManagerInvalidates all queries when the app resumes after a pause longer than minBackgroundDuration.
FlutterConnectivityManagerEmits NetworkStatus events; reconnect logic is delegated to QoraClient via reconnectStrategy.

QoraScope automatically calls start() and dispose() on both managers: no manual lifecycle wiring required.

Shorthand: QoraScope.auto()

For convenience, use QoraScope.auto() to wire both managers in a single call:

main.dart
void main() {
  runApp(
    QoraScope.auto(
      client: QoraClient(),
      child: const MyApp(),
    ),
  );
}

This is equivalent to manually passing FlutterLifecycleManager and FlutterConnectivityManager. Use enableLifecycle and enableConnectivity to disable specific listeners:

main.dart
QoraScope.auto(
  client: QoraClient(),
  enableLifecycle: false,               // disable refetch-on-resume
  enableConnectivity: false,            // disable refetch-on-reconnect
  minBackgroundDuration: const Duration(seconds: 30),
  child: const MyApp(),
)
ParameterTypeDefaultDescription
enableLifecyclebooltrueEnables FlutterLifecycleManager (refetch on app resume).
enableConnectivitybooltrueEnables FlutterConnectivityManager (refetch on reconnect).
minBackgroundDurationDurationDuration(seconds: 5)Minimum pause before invalidation on resume.

Next Steps

  • QoraScope: Detailed API and nested scope patterns
  • QoraBuilder: Fetching data and rendering states in widgets

Offline & Network

What Qora does with reads and writes while the device is offline, what happens on reconnect, and what survives an app restart.

QoraScope

The StatefulWidget that provides a QoraClient to your widget tree and manages the lifecycle of optional platform managers.

Copyright © 2026