query_kit
TanStack Query for Dart and Flutter: cached server state with background
refetching, retries, cancellation, mutations and infinite queries — a port of
TanStack Query's query-core, checked against upstream's own test suite,
ported case by case.
Documentation: TanStack Query for Flutter at query-kit.dualmeta.io
· Quick start
· Coming from React Query
query_kit is an entirely AI-coded project: all code, tests and
documentation were written by AI coding agents (Anthropic's Claude). A human
maintainer set the goals and reviews releases, but did not write the
code. What stands in for a human author is adversarial checking:
upstream's test suite ported case by case, repeated review rounds run by
independent AI agents, and a rule that no reported finding is acted on
before it has been reproduced. Judge it on that basis; the evidence is in
this repository.
Why query_kit
- Checked against TanStack Query's own tests. Upstream's test suite is
ported case by case and run against this code: 414 of the 536 core cases
and 269 of the 305 hook cases, with every case left out listed with its
reason. How fidelity is measured.
- Four equal ways to read a query.
context.query(...), a builder
widget, a State mixin, or a controller that is a plain ValueListenable.
All four take the same options, and none of them is the default. Apps on
flutter_hooks can add useQuery with the hooks add-on.
- No dependency beyond Flutter. The binding needs Flutter and the core;
the core needs
clock and meta. Connectivity comes from whichever
package you already use.
- Results the compiler checks. A query result is a sealed type, so a
switch over pending, error and success is exhaustive and there is no
data!. A failed refetch keeps the data already on screen.
- A pure-Dart core. A server or a command-line tool uses the same cache
without Flutter, and the core's suite also runs compiled to JavaScript.
- Built to be tested. A client is an object, not a global, and time goes
through
package:clock, so a test controls staleness and garbage
collection completely.
What it does not have yet: a built-in persister and devtools.
Other Dart libraries
describes the alternatives and where each may fit better.
Packages
| Package | What it is |
|---|
query_kit | The pure-Dart core: queries, mutations, infinite queries, observers, the client and its caches. No Flutter dependency. |
query_kit_flutter | The Flutter binding: QueryClientProvider, controllers, builder widgets, a State mixin and context.query(...). Four equal call styles, no dependency beyond Flutter. Re-exports the core. |
query_kit_hooks | React Query's hooks — useQuery, useMutation and the rest — on flutter_hooks, an opt-in add-on over the binding. |
Install
In a Flutter app:
flutter pub add query_kit_flutter
In pure Dart (a server, a command-line tool):
dart pub add query_kit
In a Flutter app written with flutter_hooks, if you want the hooks:
flutter pub add query_kit_hooks flutter_hooks
The core needs Dart 3.6 or later, the binding and the hooks Flutter 3.27 or
later. Each package README has a quick start.
Documentation
The documentation site — getting started, a guide per concept, examples, the
JavaScript-to-Dart name map and troubleshooting — is built from
website/ and published at https://query-kit.dualmeta.io/. To
run it locally:
cd website && npm ci && npm start
Coming from React Query? The
name map takes the
JavaScript names to the Dart ones — useQuery to the four call styles,
fetchQuery to QueryClient.query, staleTime: Infinity to
StaleTime.infinite, and the rest.
Not in 1.0: persistence and hydration, streamedQuery, server-side
rendering and devtools.
Where this comes from, and what it is not
This is a port of TanStack Query — not a
library that was inspired by it in passing. The behaviour is upstream's, the
architecture is upstream's, and upstream's own test suite is ported case by
case — every case left out is listed with its reason — and run against this
code. That is the entire point of the project.
Thank you to Tanner Linsley and to everyone who has built, maintained and
supported TanStack Query. This repository exists for one reason: we used
TanStack Query, we loved it, and we wanted the same thing in Flutter. Every
good idea in here is theirs. It is published under their MIT licence, whose
notice each package keeps in LICENSE-TANSTACK.
It is not theirs, though. This project is not affiliated with, endorsed
by, reviewed by, or connected in any way to Tanner Linsley, the TanStack team,
or the TanStack organisation. They have not seen it and are not responsible for
it. Please do not take problems with this package to them — bugs, questions
and complaints belong in
this repository's issues.
Repository
For contributors. CONTRIBUTING.md leads with the rule that
is unusual here — a failing ported test means the port is wrong until shown
otherwise — and then the gate. Security reports go through
SECURITY.md, never a public issue.
| Path | What it is |
|---|
packages/query_kit/ | The core. Its fidelity audit — every ported upstream case, every omission and every divergence, with its reason — is PORTING_NOTES.md. |
packages/query_kit_flutter/ | The binding, and its one-file example. |
packages/query_kit_hooks/ | The hooks add-on, with its ported hook suites and its example app. |
examples/showcase/ | Every feature as its own screen, on a dummy backend built for it, each with widget tests and Playwright end-to-end tests in a real browser. |
examples/task_manager/ | One whole small app: a to-do manager against a deliberately slow backend with scripted failures. |
examples/doc_snippets/ | Every Dart sample on the site and in the package READMEs, as code the analyzer sees, so a sample that stops compiling fails the build. |
website/ | The documentation site (Docusaurus), built in CI. |
docs/ | Decisions (), research, release instructions and history. |
Working on the port needs the upstream checkout, a nested, gitignored clone
pinned to the revision the ported tests were taken from (see
CONTRIBUTING.md).
Running the tests:
flutter pub get
cd packages/query_kit && dart test
cd packages/query_kit_flutter && flutter test
cd packages/query_kit_hooks && flutter test
cd examples/showcase && flutter test
cd examples/task_manager && flutter test
cd examples/doc_snippets && flutter test
The examples' READMEs say how to run them against their backends and how to
run their end-to-end suites. The project was planned as wayfinder maps on
GitHub issues, starting with
issue #1; the one rule
that shaped everything is that closeness to upstream is a tiebreaker, not a
goal — where a Dart or Flutter idiom is better, the port diverges and writes
down why.
Licence
MIT — see the LICENSE in each package. The ported tests are derived from
upstream TanStack Query's MIT-licensed suite; its licence is LICENSE-TANSTACK
in each package.
