# Qora

> Server-state library for Flutter and Dart: caching, background refresh, queries that pause offline, and a queue that replays writes on reconnect. Inspired by TanStack Query, with a different API and no code generation.

## Documentation Sets

- [Qora documentation](https://qora.meragix.dev/llms-full.txt): The complete English documentation of Qora.

## Documentation

- [What is Qora?](https://qora.meragix.dev/raw/en/getting-started/what-is-qora.md): Qora fetches, caches and synchronizes server data in Flutter and Dart, and keeps your app usable when the network is not.
- [Installation](https://qora.meragix.dev/raw/en/getting-started/installation.md): Add Qora to a Flutter app or a pure Dart project, and wire it in one widget.
- [Quick Start](https://qora.meragix.dev/raw/en/getting-started/quick-start.md): Build a list and a detail screen backed by Qora, watch the cache work, then take the app offline.
- [Comparison](https://qora.meragix.dev/raw/en/getting-started/comparison.md): How Qora compares to flutter_query and cached_query, the other server-state libraries for Flutter.
- [Coming from TanStack Query](https://qora.meragix.dev/raw/en/getting-started/coming-from-tanstack-query.md): A precise mapping of TanStack Query concepts, hooks, and configuration options to their Qora equivalents. Covers what is identical, what is renamed, and what works differently.
- [Migrating from Other Libraries](https://qora.meragix.dev/raw/en/getting-started/migrating-from-other-libraries.md): Map flutter_query and cached_query concepts to Qora and migrate one screen at a time.
- [AI Assistants](https://qora.meragix.dev/raw/en/getting-started/ai-assistants.md): Give Claude, Cursor, Copilot or any coding assistant the context it needs to write correct Qora code.
- [Queries](https://qora.meragix.dev/raw/en/core-concepts/queries.md): Queries are the foundation of Qora. A query is an async request bound to a key, with automatic caching, deduplication, retries, and reactive state.
- [Query Keys](https://qora.meragix.dev/raw/en/core-concepts/query-keys.md): Query keys are the foundation of Qora's caching system. They uniquely identify queries and enable automatic cache management, invalidation, and refetching.
- [Query States](https://qora.meragix.dev/raw/en/core-concepts/query-states.md): Query states represent the lifecycle of your data fetching operations. Qora uses sealed classes to provide exhaustive, type-safe state handling that eliminates entire categories of runtime errors.
- [Caching](https://qora.meragix.dev/raw/en/core-concepts/caching.md): Qora's cache enables instant data access. Learn how cache entries are created, aged, and garbage collected, how structural sharing prevents unnecessary rebuilds, and how to control each behavior.
- [Stale-While-Revalidate](https://qora.meragix.dev/raw/en/core-concepts/stale-while-revalidate.md): Qora SWR returns cached data immediately and revalidates in the background to keep UIs responsive and data current.
- [Deduplication](https://qora.meragix.dev/raw/en/core-concepts/deduplication.md): Qora merges concurrent requests for the same key into a single network call, regardless of the number of callers.
- [Mutations & Invalidation](https://qora.meragix.dev/raw/en/core-concepts/mutations.md): How writes run, in which order their callbacks fire, and the three ways to bring the cache back in line with the server afterwards.
- [Offline & Network](https://qora.meragix.dev/raw/en/core-concepts/offline.md): What Qora does with reads and writes while the device is offline, what happens on reconnect, and what survives an app restart.
- [Setup](https://qora.meragix.dev/raw/en/flutter-integration/setup.md): Install qora_flutter, create a QoraClient instance, and provide it to the widget tree with QoraScope.
- [QoraScope](https://qora.meragix.dev/raw/en/flutter-integration/qora-scope.md): The StatefulWidget that provides a QoraClient to your widget tree and manages the lifecycle of optional platform managers.
- [QoraBuilder](https://qora.meragix.dev/raw/en/flutter-integration/qora-builder.md): The widget that fetches data, subscribes to state changes, and rebuilds your UI on every state transition.
- [QoraMutationBuilder](https://qora.meragix.dev/raw/en/flutter-integration/qora-mutation-builder.md): The widget that manages a MutationController lifecycle and rebuilds your UI on every mutation state transition.
- [InfiniteQueryBuilder](https://qora.meragix.dev/raw/en/flutter-integration/infinite-query-builder.md): The widget that manages paginated queries and exposes fetchNextPage, fetchPreviousPage, and refetch through a stable controller interface.
- [Hooks (flutter_hooks)](https://qora.meragix.dev/raw/en/flutter-integration/hooks.md): Use useQuery, useMutation, useInfiniteQuery, useIsFetching and useIsMutating with flutter_hooks for a concise, composable API.

- [Network Status Widgets](https://qora.meragix.dev/raw/en/flutter-integration/network-status.md): NetworkStatusBuilder and NetworkStatusIndicator: reactive widgets for displaying offline state in Flutter apps.
- [Best Practices](https://qora.meragix.dev/raw/en/flutter-integration/best-practices.md): Patterns and conventions for building reliable Flutter apps with Qora: keys, query placement, mutation wiring, and performance.
- [Mutations](https://qora.meragix.dev/raw/en/recipes/mutations.md): Perform write operations (POST, PUT, DELETE) with full lifecycle support: optimistic updates, automatic rollback, retry, and DevTools observability.
- [Optimistic Updates](https://qora.meragix.dev/raw/en/recipes/optimistic-updates.md): Update the UI instantly while mutations are in flight, and roll back safely on failure: with no extra libraries.
- [Persistence](https://qora.meragix.dev/raw/en/recipes/persistence.md): Persist query results to disk and restore them on startup: giving your app an instant data layer that works fully offline.
- [Network Aware](https://qora.meragix.dev/raw/en/recipes/network-aware.md): Handle offline mode, paused queries, offline mutation queuing, and reconnect replay with Qora's network-aware layer.
- [Infinite Queries](https://qora.meragix.dev/raw/en/recipes/infinite-queries.md): Implement forward and bi-directional pagination with InfiniteQueryObserver: load more on scroll, pull-to-refresh, windowed paging, and cursor-based APIs.
- [Dependent Queries](https://qora.meragix.dev/raw/en/recipes/dependent-queries.md): Use QoraOptions.dependsOn to chain queries so one fires only after another resolves.
- [Cancellation](https://qora.meragix.dev/raw/en/recipes/cancel-token.md): Use CancelToken to abort in-flight fetches cooperatively: on navigation, timeout, or user action.
- [SSR Hydration](https://qora.meragix.dev/raw/en/recipes/ssr-hydration.md): Eliminate the loading flash on server-rendered Flutter Web pages by injecting the server cache into QoraClient via SsrHydrator.
- [Error Handling](https://qora.meragix.dev/raw/en/recipes/error-handling.md): Understand how Qora surfaces errors, configures retry behaviour, and enables graceful degradation with previousData.
- [Testing](https://qora.meragix.dev/raw/en/recipes/testing.md): Test Qora queries, mutations, and widgets with deterministic helpers: no network, no Hive, no timers.
- [Route-Level Prefetching](https://qora.meragix.dev/raw/en/recipes/prefetch.md): [object Object]
- [QoraClient](https://qora.meragix.dev/raw/en/api-reference/qora-client.md): The central engine of Qora: manages queries, cache, deduplication, retries, and reactive state
- [QoraKey](https://qora.meragix.dev/raw/en/api-reference/qora-key.md): Typed, immutable query key with structural equality. Supports both raw List and QoraKey syntax.
- [QoraState](https://qora.meragix.dev/raw/en/api-reference/qora-state.md): Sealed class hierarchy representing the four possible states of a query. Exhaustive pattern matching is enforced at compile time.
- [QoraOptions](https://qora.meragix.dev/raw/en/api-reference/qora-options.md): Per-query configuration that overrides QoraClientConfig defaults. Pass to fetchQuery or watchQuery to customise caching, retries, staleness, and polling.
- [QoraClientConfig](https://qora.meragix.dev/raw/en/api-reference/qora-client-config.md): Global configuration for QoraClient. Applied as the baseline for every query. Per-query QoraOptions are merged on top.
- [Mutation API](https://qora.meragix.dev/raw/en/api-reference/qora-mutation.md): Complete API reference for MutationController, MutationState, MutationOptions, MutationUpdate, and mutation observability on QoraClient.
- [PersistQoraClient](https://qora.meragix.dev/raw/en/api-reference/persist-qora-client.md): A QoraClient subclass that persists query results to a StorageAdapter and restores them on startup via hydrate().
- [Infinite Query](https://qora.meragix.dev/raw/en/api-reference/infinite-query.md): Full API reference for InfiniteData, InfiniteQueryState, InfiniteQueryOptions, InfiniteQueryObserver, InfiniteQueryBuilder, InfiniteQueryController, and the QoraClient infinite-query methods.
- [Overview](https://qora.meragix.dev/raw/en/devtools/overview.md): See every query, mutation and cache entry of the running app, and act on them, from a panel inside the app.
- [In-App Overlay](https://qora.meragix.dev/raw/en/devtools/overlay.md): A floating debug panel rendered inside the Flutter app. Inspect queries, mutations, and optimistic updates without an external tool.
- [Data Serialization](https://qora.meragix.dev/raw/en/devtools/data-display.md): How cached query data is turned into the JSON tree shown in the overlay, and how to make custom model types readable.
- [With Provider](https://qora.meragix.dev/raw/en/third-party/with-provider.md): Add Qora to an existing Provider app to specialize server-state handling while preserving Provider for UI state and dependency injection.
- [With BLoC](https://qora.meragix.dev/raw/en/third-party/with-bloc.md): Use Qora for server-state and BLoC for UI state machines, with explicit separation of concerns.
- [With Riverpod](https://qora.meragix.dev/raw/en/third-party/with-riverpod.md): Add Qora to a Riverpod project to complement FutureProvider with SWR, offline behavior, and hooks-oriented query APIs.
- [With RxDart](https://qora.meragix.dev/raw/en/third-party/with-rxdart.md): Reactive key management with RxDart and QoraClient, dynamic query switching with guaranteed resource cleanup.
- [With Dio](https://qora.meragix.dev/raw/en/third-party/with-dio.md): [object Object]
- [With GraphQL](https://qora.meragix.dev/raw/en/third-party/with-graphql.md): Wrap graphql or ferry GraphQL clients in Qora fetchers for seamless query management with stale-while-revalidate, cache invalidation, and pagination.
- [Case Study: User List & Detail](https://qora.meragix.dev/raw/en/examples/basic-query.md): A complete list-and-detail feature: SWR caching, FetchStatus two-axis state, per-item query keys, pull-to-refresh, and graceful degradation. Zero boilerplate state management.
- [Case Study: Optimistic Mutations & Rollback](https://qora.meragix.dev/raw/en/examples/mutations-optimistic.md): A complete optimistic update implementation: setQueryData for immediate UI feedback, restoreQueryData for automatic rollback on failure, and invalidateWhere for server reconciliation.
- [Case Study: Infinite Scroll Feed](https://qora.meragix.dev/raw/en/examples/infinite-scroll.md): Build a high-performance social media-style feed with cursor-based pagination, windowed memory management, and instant optimistic post creation.
- [Case Study: Offline-First Todo App](https://qora.meragix.dev/raw/en/examples/offline-first.md): A todo app that keeps working without a network: saved data on start, queries that pause offline, and writes queued and replayed in order on reconnect.
- [Case Study: Network Awareness](https://qora.meragix.dev/raw/en/examples/network-awareness.md): Queries pause automatically when offline, mutations queue for later, and everything replays on reconnect: with thundering-herd prevention built in.
- [Case Study: Hooks Integration](https://qora.meragix.dev/raw/en/examples/hooks-integration.md): Replace QoraBuilder widget nesting with flat, composable hook calls: useQuery, useMutation, useInfiniteQuery, and global fetch indicators in a HookWidget
- [Case Study: Complete Todo App](https://qora.meragix.dev/raw/en/examples/complete-todo-app.md): A production-grade Flutter app combining every Qora capability: PersistQoraClient, infinite scroll with pagination, optimistic create/toggle/delete, offline mutation queue, and simulated connectivity toggling.
- [FAQ](https://qora.meragix.dev/raw/en/help/faq.md): Answers to common questions about Qora's API, cache semantics, and Flutter integration.
- [Troubleshooting](https://qora.meragix.dev/raw/en/help/troubleshooting.md): Diagnose and resolve common Qora issues, including persistence failures, blocked queries, missing refetches, and repeated widget subscriptions.

## Notes

- Rules for coding assistants, with the most common mistakes: https://qora.meragix.dev/qora-rules.md
- Flutter apps depend on qora_flutter (it re-exports qora); hook users add qora_hooks.
- QoraState is sealed (Initial, Loading, Success, Failure): render it with an exhaustive switch. There is no state.when().
- Offline, queries pause: Loading with FetchStatus.paused, never Failure or Initial.
- invalidate() and MutationOptions.invalidates match exact keys; use invalidatePrefix() for a family of keys.