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.