Qora
Getting Started

Installation

Add Qora to a Flutter app or a pure Dart project, and wire it in one widget.

Flutter

Add the dependency

Terminal
flutter pub add qora_flutter

This adds qora_flutter: ^1.3.1 to pubspec.yaml. It brings qora and connectivity_plus with it; no other entry is needed.

Wrap your app

Create one QoraClient and put it above your app with QoraScope.auto:

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: QoraClientConfig(
      defaultOptions: const QoraOptions(staleTime: Duration(minutes: 5)),
      debugMode: kDebugMode,
    ),
  );

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

QoraScope.auto also starts two managers, so you get these behaviours without extra code:

  • Lifecycle: when the app comes back to the foreground after at least 5 seconds, stale queries that are on screen refetch.
  • Connectivity: queries pause while the device is offline and refetch when it reconnects.

Use it

Any widget below QoraScope can now use QoraBuilder, QoraMutationBuilder, or context.qora for imperative calls. The Quick Start builds a first screen.

Configuration notes

  • staleTime is how long fetched data counts as fresh. The default is zero: data is always stale and revalidated in the background when a widget mounts. Five minutes is a reasonable starting point for most screens.
  • debugMode: kDebugMode prints cache activity in debug builds only.
  • To tune the managers (for example a longer background delay), pass them yourself with the default constructor:
main.dart
runApp(
  QoraScope(
    client: client,
    lifecycleManager: FlutterLifecycleManager(
      qoraClient: client,
      minBackgroundDuration: const Duration(seconds: 30),
    ),
    connectivityManager: FlutterConnectivityManager(),
    child: const MyApp(),
  ),
);

QoraScope without managers works too, but then nothing refetches on resume or reconnect.

Hooks

If your app uses flutter_hooks, add qora_hooks as well:

Terminal
flutter pub add qora_hooks flutter_hooks

Setup is the same QoraScope.auto. See Hooks.

Pure Dart

For CLIs, servers and shared packages, use the core package. It has no Flutter dependency:

Terminal
dart pub add qora
bin/main.dart
import 'package:qora/qora.dart';

Future<void> main() async {
  final client = QoraClient(
    config: const QoraClientConfig(
      defaultOptions: QoraOptions(staleTime: Duration(minutes: 5)),
    ),
  );

  // One-shot fetch: cached, deduplicated, retried on failure.
  final user = await client.fetchQuery<User>(
    key: ['users', 1],
    fetcher: () => api.getUser(1),
  );
  print('User: ${user.name}');

  // Still fresh: served from the cache, no network call.
  await client.fetchQuery<User>(key: ['users', 1], fetcher: () => api.getUser(1));

  client.dispose();
}

watchQuery returns a stream of every state transition when you need reactivity outside Flutter. See Queries.

DevTools overlay (optional)

Terminal
flutter pub add qora_devtools_overlay

See In-App Overlay for setup. It is a regular dependency because your main.dart imports it; in release builds it renders nothing and its UI is removed by tree shaking.

Next Steps

What is Qora?

Qora fetches, caches and synchronizes server data in Flutter and Dart, and keeps your app usable when the network is not.

Quick Start

Build a list and a detail screen backed by Qora, watch the cache work, then take the app offline.

Copyright © 2026