zino-hofmann/graphql-flutter
58.5
Adequate · 12 November 2026
8.5k
lines of production code
Dart
primary language
7
measurements over time
What this system is
This system is a GraphQL client library for Dart and Flutter, providing core networking capabilities for executing queries, mutations, and real-time subscriptions via HTTP and WebSocket links. It features a robust, configurable cache with strict data normalization and optional Hive persistence for offline support, alongside utilities for request cancellation and polling. The project also includes a companion Flutter package that exposes declarative widgets and hooks for integrating GraphQL data into Flutter applications.
How it got here
2018–2019 — v5 monorepo migration and hooks rewrite
28 changes.
The project was restructured into a monorepo using Melos and migrated to GraphQL Dart 5.x and Flutter 5.x, introducing a comprehensive rewrite of the client's cache and execution engine. This period saw the adoption of Flutter Hooks for the graphql\_flutter package, the addition of request cancellation and strict cache policies, and the creation of extensive examples and test suites to support the new architecture.
2020–2026 — Flutter hooks and WebSocket modernization
8 changes.
This period focused on modernizing the GraphQL client infrastructure by rewriting the WebSocket link for better protocol support and introducing a declarative Flutter Hooks API for easier state management. Significant effort was also dedicated to enhancing local persistence with Hive storage utilities and expanding test coverage across cache, links, and widget components to ensure stability.
Features
Add cancellation support for queries and mutations
The \graphql\ client now supports cancelling in-flight HTTP requests. A new \CancellableHttpLink\ is provided, which uses the \http\ package's abort capabilities to terminate network requests when a \CancellationToken\ is present in the request context. Users can trigger this via the new \queryCancellable\ and \mutateCancellable\ methods, or by manually passing a \CancellationToken\ to standard query/mutation options.
packages/graphql · high confidence
Add pagination example using fetchMore
The example app now includes a new 'fetchMore' demo that illustrates how to implement pagination in GraphQL Flutter. The example configures a GraphQL client with an HttpLink and GraphQLCache, then uses a Query widget to fetch repository search results. It demonstrates the fetchMore mechanism by allowing users to load additional pages of results via a 'Load More' button, combining previous and new data using an updateQuery function, and handling loading states and exceptions appropriately.
_packages/graphql\flutter/example/lib/fetchmore · high confidence
Added helper to initialize Hive storage for Flutter
A new \initHiveForFlutter\ utility has been added to the library to simplify setting up local persistence. This function ensures the Flutter binding is initialized, determines the correct application documents directory (excluding web platforms), and concurrently opens the specified Hive boxes, allowing users to easily configure offline caching for GraphQL queries.
_packages/graphql\flutter/lib/src · high confidence
Configurable request timeout and cancellation support
The GraphQL client now supports configurable request timeouts via the new \queryRequestTimeout\ parameter in the constructor and \copyWith\ method, allowing users to override the default 5-second limit. Additionally, the client exposes cancellation support for queries and mutations, enabling users to abort in-flight operations.
packages/graphql/lib/src · high confidence
Example app adds GraphQL operations for repository management and subscriptions
The example application now includes concrete GraphQL operation definitions for interacting with repository data. Users can see examples of mutations to add or remove stars on starrable items, queries to list and search repositories with pagination support, and a subscription example for real-time device updates. These files provide a reference implementation for common GraphQL patterns within the Flutter environment.
_packages/graphql\_flutter/example/lib/graphql\operation · high confidence
Example application entry point created
The example application's main entry point file (main.dart) has been added to the project structure.
example · high confidence
Initial release of graphql\_flutter package with hooks and Hive support
The graphql\_flutter package is now available, providing a public entry point that exports core GraphQL widgets (Provider, Consumer, Query, Mutation, Subscription), a new ResultAccumulator widget, and a set of Flutter Hooks (useQuery, useMutation, useSubscription, useWatchQuery, useGraphQLClient). It also exposes Hive initialization utilities via hive\_init.dart, enabling users to integrate Hive caching with Flutter.
_packages/graphql\flutter/lib · high confidence
New BLoC-based example for GraphQL operations
The example application now includes a new \graphql\_bloc\ directory demonstrating a BLoC (Business Logic Component) pattern for managing GraphQL state. This example features a \Bloc\ class that handles repository queries and star/unstar mutations using \GraphQLClient\, exposing state via \Stream\ and \Sink\ interfaces. The accompanying UI (\main.dart\) uses \StreamBuilder\ widgets to reactively display the list of repositories and loading states, allowing users to update the number of fetched repositories and toggle stars on individual items.
_packages/graphql\_flutter/example/lib/graphql\bloc · high confidence
New CLI example for GitHub GraphQL API interactions
The example package now includes a command-line interface (bin/example.dart) that allows users to fetch their GitHub repositories, as well as star and unstar specific repositories via GraphQL mutations. This CLI relies on a new main library (lib/main.dart) containing the query and mutation logic, and requires users to provide a GitHub personal access token via a local configuration file (lib/local.dart) to authenticate requests.
packages/graphql/example/lib · high confidence
New Flutter Hooks API for GraphQL operations
The \graphql\_flutter\ package now provides a set of Flutter Hooks (\useQuery\, \useMutation\, \useSubscription\, \useWatchQuery\) that allow developers to integrate GraphQL data fetching directly into their widget trees using the \flutter\_hooks\ library. This change introduces a new \useGraphQLClient\ hook to access the client from context and implements the underlying hook states for managing query streams, mutation execution, and subscription connectivity (including network change detection). Users can now replace traditional provider-based or imperative query patterns with declarative hooks that automatically handle lifecycle management, result snapshots, and refetching.
_packages/graphql\flutter/lib/src/widgets/hooks · high confidence
New GraphQL Widget example screen
The example application now includes a new GraphQL Widget screen that demonstrates querying GitHub repositories and handling mutations with optimistic updates. This screen sets up a GraphQL client with an HTTP link and cache, then uses the Query widget to fetch a list of repositories based on a user-specified count, and the Mutation widget to handle starring/unstarring repositories with local cache updates.
_packages/graphql\_flutter/example/lib/graphql\widget · high confidence
New QueryScheduler with configurable polling deduplication
A new QueryScheduler class has been introduced to manage polling intervals for ObservableQueries. This component allows multiple queries to share a single timer when they request the same polling interval, optimizing resource usage. It includes a configurable \deduplicatePollers\ flag (defaulting to false) that, when enabled, ensures only the fastest polling query for a specific request is active, preventing redundant network requests. The scheduler handles starting, stopping, and cleaning up polling timers based on registered query options.
packages/graphql/lib/src/scheduler · high confidence
New authentication and GraphQL link exports
The \packages/graphql/lib/src/links\ area now exposes a new \AuthLink\ that automatically attaches an authorization header (defaulting to 'Authorization') to every GraphQL request using a provided token getter. Additionally, this location re-exports core \gql\ library links (HTTP, error handling, deduplication) alongside the new authentication link and the updated WebSocket link, centralizing these networking components for easier access.
packages/graphql/lib/src/links · high confidence
New consolidated client entry point
A new \client.dart\ library file has been introduced to serve as the primary entry point for the GraphQL package. It re-exports core components including the cache, core query logic, policies, exceptions, the main GraphQL client, and the links layer, along with utility helpers like \gql\ and \optimizedDeepEquals\, simplifying how users import these features.
packages/graphql/lib · high confidence
Repository initialization with monorepo tooling and documentation
The repository is initialized as a monorepo for the graphql-flutter project, introducing \melos\ for package management and CI orchestration via a new \Makefile\ and \melos.yaml\. The project structure includes dedicated packages for the core client (\graphql\) and Flutter widgets (\graphql\_flutter\), supported by a \changelog-v3-v4.md\ migration guide detailing cache overhauls, the adoption of the \gql\_link\ system, and subscription API changes. Developer experience is enhanced with a \flake.nix\ development shell, \.codecov.yml\ for coverage reporting, and an \.all-contributorsrc\ file to automate contributor recognition in the README.
(repo-wide) · high confidence
Star Wars demo example restructured with web support and subscriptions
The Star Wars demo example has been restructured into a new layout, adding support for web platforms (Flutter for Web) and real-time GraphQL subscriptions. The app now features a top-level navigation bar with three tabs: Episodes (querying hero data), Reviews (displaying a live feed via WebSocket subscriptions), and Paging (demonstrating paginated query loading). It also includes a local Hive cache for state management and a Makefile to simplify running the local server and client.
examples/starwars · high confidence
Removals
Removal of lib/graphql.dart and Calculator class
The file lib/graphql.dart has been removed from the library. This deletion eliminates the previously exported Calculator class and its addOne method, meaning this functionality is no longer available to consumers of the library.
lib · high confidence
Behavioural changes
Cache overhaul with strict partial data handling and Hive persistence
The GraphQL cache has been rewritten to use the \normalize\ library (v0.4.2) for data normalization, introducing a new \PartialDataCachePolicy\ that allows you to configure whether writes with missing fields are accepted or rejected (throwing \PartialDataException\ or \CacheMisconfigurationException\). The cache now supports persistent storage via a new \HiveStore\ (migrated to \hive\_ce\), while retaining the default in-memory store. Additionally, \possibleTypes\ are now exposed on the cache for union/interface support, and optimistic transactions have been restructured to use a new \OptimisticProxy\ with hierarchical patching.
packages/graphql/lib/src/cache · high confidence
Core execution engine refactored with cancellation, strict policies, and typed results
The core GraphQL execution layer has been restructured to support new capabilities and stricter behavior. Operations can now be cancelled mid-flight using a new \CancellationToken\ API, which terminates in-flight requests and returns a \CancelledException\. Cache interaction is now governed by a unified \Policies\ class (wrapping \FetchPolicy\, \ErrorPolicy\, and \CacheRereadPolicy\), enabling configurable rebroadcasting and optimistic data merging. Cache writes are now strict: malformed data triggers \PartialDataException\ or \CacheMisconfigurationException\ rather than failing silently. Result handling is more precise with \QueryResultSource\ tracking (cache, network, optimistic) and a \parsedData\ getter for typed results, while \ObservableQuery\ lifecycle states and refetch safety checks have been tightened to prevent invalid state transitions.
packages/graphql/lib/src/core · high confidence
Example app migrated to Flutter V2 Android embedding
The Android configuration for the graphql\_flutter example app has been updated to use the Flutter V2 embedding. This includes adding the \flutterEmbedding\ meta-data to the main AndroidManifest.xml, switching MainActivity to extend \FlutterActivity\, and updating resource styles to support the V2 theming model. Users running the example on Android will benefit from the updated embedding architecture required by newer Flutter versions.
_packages/graphql\flutter/example/android · high confidence
Example project configuration and documentation updates
The graphql\_flutter example project has been updated with standard Flutter project scaffolding, including a new .gitignore file to exclude build artifacts and IDE files, a .metadata file tracking the beta channel revision, and a README.md providing setup instructions. Additionally, analysis\_options.yaml has been added to enforce the pedantic linting style for CI consistency, with the flutter\_style\_todos rule explicitly disabled.
_packages/graphql\flutter/example · high confidence
Exception handling migrated to gql\_link with new cache and cancellation errors
The GraphQL client's exception hierarchy has been refactored to extend \gql\_link\'s \LinkException\, replacing the previous base classes. This introduces specific error types for new behaviors: \CancelledException\ for operation cancellations, \CacheMissException\ for missing cache data, and \CacheMisconfigurationException\ or \MismatchedDataStructureException\ when cache writes fail due to data structure mismatches. Network errors are now wrapped in \NetworkException\ (with the default constructor deprecated in favor of \fromException\), and unknown client-side errors are captured in \UnknownException\ with full stack traces. The \OperationException\ class now includes a \raw\ field to expose raw response data alongside GraphQL errors and link exceptions.
packages/graphql/lib/src/exceptions · high confidence
GraphQL Flutter example app restructured with new demo screens
The example application has been reorganized to provide a central navigation hub for four distinct usage patterns: the GraphQL BLoC pattern, the GraphQL Widget pattern, a FetchMore (pagination) example, and a new Cancellation demo. A new helper utility was added to standardize loading and exception handling across query builders, and a local configuration file was introduced for token management.
_packages/graphql\flutter/example/lib · high confidence
Introduce Flutter Hooks-based GraphQL widgets
The widget layer has been rewritten to use Flutter Hooks, replacing the previous StatefulWidget-based implementation. New hook-driven widgets—Query, Mutation, and Subscription—now manage their own state and lifecycle internally, simplifying usage by removing the need for complex nested builders or manual state management. A new GraphQLProvider widget exposes the GraphQLClient via an InheritedWidget, enabling these hooks to access the client context. Additionally, a ResultAccumulator widget is provided to help manage and display multiple results from subscription streams.
_packages/graphql\flutter/lib/src/widgets · high confidence
Migrate graphql\_flutter iOS example to modern Xcode project structure
The iOS example project for graphql\_flutter has been regenerated to use the current Flutter iOS template. This updates the Xcode project configuration (project.pbxproj), workspace settings, and build scripts to align with modern Flutter tooling, ensuring the example builds correctly with recent versions of Xcode and the Flutter SDK.
_packages/graphql\flutter/example/ios · high confidence
New utility helpers, platform-specific WebSocket support, and error-handling response mapping
This change introduces several new utility components in the GraphQL package. It adds platform-specific WebSocket connection logic, allowing custom headers on server-side (IO) while printing a warning and ignoring headers on the browser (HTML), making WebSockets usable across both environments. It also introduces a new \response.dart\ that maps fetch results to \QueryResult\ objects, correctly handling \ErrorPolicy\ settings (all, ignore, none) and populating the \exception\ field with raw errors. Additionally, \helpers.dart\ provides new utilities including \deeplyMergeLeft\ for merging maps, \gql\ for parsing documents with automatic \\_\_typename\ addition, \sanitizeFilesForCache\ for converting \MultipartFile\ objects to cache-safe strings, and \optimizedDeepEquals\ for efficient deep equality checks.
packages/graphql/lib/src/utilities · high confidence
WebSocket link rewritten with \`web\_socket\_channel\` and \`graphql-transport-ws\` support
The WebSocket link implementation has been completely rewritten to use the \web\_socket\_channel\ package instead of the previous \ws\ library, improving platform compatibility and stability. This change introduces native support for the \graphql-transport-ws\ protocol (used by modern Apollo Server instances) alongside the legacy \graphql-ws\ protocol, with the latter now deprecated in favor of the new standard. Users benefit from more robust connection management, including automatic reconnection, customizable ping payloads, and better handling of connection loss and timeouts. The API has been updated to use \SocketClientConfig\ for configuration, allowing for custom headers, initial payloads, and connection functions, while ensuring null-safety throughout the client.
_packages/graphql/lib/src/links/websocket\link · high confidence
graphql\_flutter v5.3.0 release with stricter analysis and cancellation example
This release introduces stricter static analysis rules (strict-casts, strict-inference, strict-raw-types) to improve code quality and catch potential issues early. It also includes a new example demonstrating request cancellation using CancellableHttpLink, which allows aborting HTTP requests at the network level. The package now requires Java 17 for Android builds and updates several dependencies including connectivity\_plus, http, and flutter\_hooks to fix build issues and ensure compatibility.
_packages/graphql\flutter · high confidence
Fixes
Restored iOS project files for the Starwars example
The iOS configuration files for the Starwars example app have been restored, including the Xcode project, workspace, schemes, and native runner code. This ensures the example can be built and run on iOS devices and simulators again.
examples/starwars/ios · high confidence
Test coverage
Added comprehensive test suite for GraphQL client functionality; Added local test server for cancellation demo; Added tests for GraphQL cache normalization, optimistic transactions, and Hive store persistence; Added widget test for GraphQLConsumer; Added widget tests for Query and Subscription components; Removed obsolete GraphQL test file.
Dependencies
Migrate to GraphQL Dart 5.x and Flutter 5.x with updated dependencies
The graphql and graphql\_flutter packages have been upgraded to versions 5.2.4 and 5.3.0 respectively, aligning with the GraphQL Dart 5.x and Flutter 5.x ecosystems. This update introduces several dependency changes: the core graphql package now depends on gql packages (gql, gql\_exec, gql\_link, etc.) version 1.0.0+, uses hive\_ce ^2.11.0 for caching, and updates http to ^1.6.0 and web\_socket\_channel to \>=3.0.1. The graphql\_flutter package now requires connectivity\_plus ^7.0.0, hive\_ce ^2.13.2, and path\_provider ^2.1.5, while restricting flutter\_hooks to \<0.22.0. Both packages now require Dart SDK \>=3.0.0. The examples (starwars and graphql\_flutter example) have been updated to reflect these new dependencies and platform configurations, including AndroidX support and updated Gradle/Kotlin versions for the Flutter example.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 55 → 59 (+3.8)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.3) — scores are not directly comparable.
Lenses
- Code Health 93 → 93 (+0.0)
- Architecture 96 → 96 (+0.0)
- Maturity 54 → 64 (+9.7)
- Readiness 41 → 46 (+4.9)
- Security 56 → 56 (+0.0)
- Domain Modelling 100 → 100 (+0.0)
- Performance 100 → 100 (+0.0)
Resolved (5)
- Documentation: no installation or build instructions (README.md)
- Documentation: no project overview (README.md)
- Documentation: no usage examples (README.md)
- Duplicated block (12 lines × 2) (packages/graphql_flutter/example/lib/graphql_widget/main.dart)
- Off-boarding risk: anonymized user #1
New (13)
- Duplicated block (9 lines × 2) (packages/graphql_flutter/example/lib/graphql_widget/main.dart)
- Edited copies of one member (3 members, 14+ corresponding lines) (packages/graphql/lib/src/core/mutation_options.dart)
- Edited copies of one member (5 members, 18+ corresponding lines) (packages/graphql/lib/src/core/query_options.dart)
- Edited copy of a member (10 corresponding lines) (packages/graphql/lib/src/core/mutation_options.dart)
- Edited copy of a member (10 corresponding lines) (packages/graphql/lib/src/core/mutation_options.dart)
- Edited copy of a member (12 corresponding lines) (packages/graphql/lib/src/core/_base_options.dart)
- Edited copy of a member (13 corresponding lines) (packages/graphql/lib/src/core/_base_options.dart)
- Edited copy of a member (14 corresponding lines) (packages/graphql/lib/src/core/query_options.dart)
- Edited copy of a member (19 corresponding lines) (packages/graphql/lib/src/cache/_normalizing_data_proxy.dart)
- Edited copy of a member (20 corresponding lines) (packages/graphql_flutter/example/lib/fetchmore/main.dart)
- Edited copy of a member (37 corresponding lines) (packages/graphql/lib/src/cache/_normalizing_data_proxy.dart)
- Edited copy of a member (8 corresponding lines) (packages/graphql/lib/src/cache/fragment.dart)
- Off-boarding risk: anonymized user #1
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
zino-hofmann/graphql-flutter was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 12 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit f6fa354441bf457967c31b3b66406f8360d143b2 — the exact code this score is about.
- Scored under rubric-2026.11.3 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.42+preprod-6bc2a431cb25.