graphql-flutter: a Dart GraphQL client for Flutter apps that need caching and streams

What graphql-flutter solves for Flutter teams

A Flutter app that talks to a GraphQL server has to handle four things at once: sending operations, keeping a local copy of the data so screens do not refetch on every rebuild, merging the result of a mutation into that copy, and turning all of it into something a widget can listen to. The graphql-flutter monorepo splits that work across two packages. The graphql package is the client itself and has no Flutter dependency, so it can be used from plain Dart. The graphql_flutter package wraps it in widgets. The README describes the goal as combining GraphQL with Dart Streams to deliver a high-performance client, and names the Apollo GraphQL client as its inspiration. That is a fair description of the design: operations are exposed as streams you subscribe to, rather than as one-shot futures you await and then discard. The intended audience is a Flutter or Dart developer who already has a GraphQL endpoint and does not want to write a caching layer or a request pipeline. If your app calls a REST API and you are happy with it, this package gives you nothing.

How the client is structured: links, cache and streams

The client is built from three visible pieces. First, a link chain. The README lists modularity as a feature and points at the links section of the graphql README, so requests travel through composable links that each do one job, which is how the upload link and the persisted queries link are described in the feature list. Second, a cache. The README advertises in-memory and persistent caching, and the graphql_flutter README has an optimism section for optimistic results, which means a mutation can write an expected value into the cache before the server answers. Third, an observable query. The graphql README documents Client.watchQuery and ObservableQuery, and the feature list adds query polling and rebroadcasting. A widget subscribes to an ObservableQuery and receives a new result whenever the cache changes, not only when a network response arrives. That is the data flow: operation goes down through the link chain, response comes back, the cache is updated, and every stream watching the affected data emits again. The README also lists operation cancellation and direct cache access, so a screen can cancel work it no longer needs and can read or write cache entries without issuing a request. The persisted queries link is marked experimental and explicitly out of service, so treat that path as unavailable rather than as a feature you can rely on.

Installing graphql_flutter and running a first query

Both packages are published on pub.dev, which is where the README links for versions. The monorepo table lists graphql as the client implementation and graphql_flutter as the Flutter widgets wrapper. In a Flutter app you depend on graphql_flutter through pubspec.yaml, the file the README describes as the Flutter dependency manifest. After editing it, run pub get so the resolver picks up the new dependency, and you should see the package listed in pubspec.lock. The next step is to wrap your app in a GraphQLProvider, which the graphql_flutter README documents; the provider takes a client, and the client needs a link pointing at your endpoint. The READMEs in packages/graphql and packages/graphql_flutter are where the exact constructor arguments live, so read those before wiring a production endpoint. Once the provider is in place, a query widget can subscribe to an operation and rebuild when the cache changes. Two things are worth checking on the first run: that your endpoint URL is reachable from the device or emulator, and that the operation you send is valid against your schema. If the provider is missing above a query widget, the widget has no client to read from, which is the most common first error.

Where graphql-flutter is the wrong tool

The clearest limitation is stated by the project itself: automatic persisted queries are flagged in the feature list as experimental and out of service. If your server rejects plain queries and requires persisted query hashes, this client will not cover that case today. The second constraint is the platform. The graphql package is Dart, and the graphql_flutter package depends on Flutter widgets, so a Kotlin, Swift or TypeScript app gets nothing from either. The third is the caching model. A normalized, schema-aware cache is not what the README describes; it describes in-memory and persistent caching plus optimistic results, which is a different bargain. Optimistic results in particular are a trade-off: you write an expected value into the cache before the server confirms it, so a rejected mutation means you own the rollback logic. The README does not document an automatic rollback path for optimistic writes. If your mutations are frequently rejected by the server, optimism will cost you more than it saves. Finally, this is a client, not a code generator. The README points at graphql_codegen as a separate tool, so if you want typed operations generated from your schema, that is a second dependency with its own setup.

graphql-flutter compared with Ferry and graphql_codegen

Ferry is the alternative most often reached for in the same situation, and the difference is in the type layer. Ferry is built around generated Dart classes for your operations, so a query is a typed object rather than a string you pass in, and the compiler catches field mismatches before the app runs. graphql-flutter keeps operations as documents you supply and resolves them at runtime against the cache. That makes graphql-flutter quicker to start with, because you do not need a codegen step in your build, and it makes Ferry stricter, because your build fails when the schema and the query disagree. graphql_codegen sits in the middle: the README lists it as a tool built around graphql_flutter, so you keep this client and add generated types on top. The choice is therefore not really client versus client. It is whether you want the type safety enforced at build time, in which case add graphql_codegen or move to Ferry, or whether you want to write documents by hand and rely on the runtime cache, in which case graphql-flutter alone is enough. The README also points at graphql_flutter_bloc for state management integration and graphql-cache-inspector for inspecting the cache, both of which assume this client is already in place.

Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-09-19. Releases are tagged per package rather than for the monorepo as a whole: v-packages-v5.3.0 on 2026-03-14, graphql-v5.2.3 on 2025-10-21, and v5.2.2 on 2025-09-07. That tagging scheme matters when you pin a version, because a tag for the client package and a tag for the widget package are separate events, and the two do not always move together. Upgrading therefore means checking which of the two packages changed and reading the changelog for that package. The Makefile shows the project is managed with melos, with targets such as dep, check, analyze, and separate changelog targets for packages/graphql and packages/graphql_flutter. That is useful if you intend to contribute or to run the test suite, but it is not something an app developer needs. The licence is MIT. In practical terms that is a permissive licence, and the repository ships a LICENSE file at the top level. Nothing here is legal advice, and if your organisation has rules about attribution or about bundling third-party code, read the LICENSE file rather than this paragraph.

What to check before you add it to a project

Start with the two package READMEs rather than the top-level one, because the feature list at the top level is a summary and the detail lives under packages/graphql and packages/graphql_flutter. The sections worth reading first are links, persistence, cancellation, and the direct cache access API in the client README, and optimism in the Flutter README. Read the optimism section before you use optimistic results anywhere near a mutation that the server can reject. Check the tag you intend to pin against the release list, and remember that the client and the widget package are versioned separately. If you need generated types, decide now whether graphql_codegen is part of your build, because retrofitting it later means rewriting your operation call sites. If you need persisted queries, verify what your server actually requires, since the README marks that link as out of service. And if your team is not writing Dart, stop here: there is no path from this repository to another language.

Editorial conclusion

Adopt graphql-flutter if your app is written in Dart or Flutter and you want a client that already speaks streams, caching and optimistic results, because rewriting that layer yourself is more work than wiring up GraphQLProvider. Do not adopt it if you need automatic persisted queries in production, since the README marks that feature as out of service, or if you are not on Flutter or Dart at all. Before committing, check the packages/graphql README for the link API and the packages/graphql_flutter README for the widget API, confirm the version you pin on pub.dev, and confirm your server does not depend on persisted queries.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. zino-hofmann/graphql-flutter on GitHub