Design notes

The reasons behind query_kit's shape are written down in the repository, next to the code. This page is a signpost: it says what each folder holds and which question it answers, and links the documents on GitHub. Nothing is copied here, so the documents stay the single source.

Two cautions. The documents are working papers written for the people building the packages, not for users, and several are in German. And they carry the project's internal bookkeeping, such as ticket numbers and review labels, which the rest of this site leaves out.

Decision records

docs/adr/ holds the decisions that are hard to reverse, each with the options that were considered and why one won.

Record	Decides
One type slot for a plain query	Why a query without select has one type argument and one with it has two, so the data type can never silently become dynamic. See type safety in Dart.
The widget-test teardown is a snippet	Why the binding does not export a test helper and no flutter_test dependency reaches your app. See testing.
Core operations own their state	Which fetch or mutation may write to a query, when a mutation scope passes on, and what a cancelled operation may no longer do.
Hooks are an add-on	Why query_kit_hooks is a separate package over a small public seam of the binding, and why hooks are not a fifth call style. See hooks.
The comparison page describes and does not rank	The rules other Dart libraries follows when it writes about other people's packages.

Research

docs/research/ holds the findings the decisions rest on. Each says what was read and when.

About TanStack Query

• Upstream query-core inventory: every module and test file of the version this port follows, and what moved since an earlier one.
• The adapter contract: what TanStack Query's own framework bindings need from the core.
• Inventory of React Query's hook tests: case by case, which can be ported to hooks.

About Dart and Flutter

• Runtime facts: timers, microtasks, error zones and lifecycle events, the guarantees the timing model depends on.
• Guards against dynamic inference: what Dart offers and what comparable libraries do. Behind the first decision record above.
• Shipping a widget-test helper: behind the second.
• Hooks spike: the measurements behind the hooks add-on.

About other packages and naming

• Other Dart libraries is the sourced comparison with the neighbouring packages; its rules are in the last decision record above.
• Package names and affiliation: which names were free on pub.dev, and what TanStack has said about community ports. See credits.

About how well it works

• The first real integration: an app using the packages unmodified reported fourteen findings. Each was checked against the code and against upstream before anything changed.
• Core confidence assessment and a test follow-up, both in German.

The API shape of the binding

docs/decisions/binding-api-shape.md records why the Flutter binding offers four call styles that behave the same, why it has no required third-party package, and why this documentation shows no default among them.

Plans

docs/plans/ holds the plans the bigger pieces of work followed, in German: the hooks package, functional improvements and what was left for after the first release (in English).

The porting notes

The audit trail of the whole port is PORTING_NOTES.md in the core package's tests, with the hooks add-on's own beside it. They list every upstream test that was ported, adapted or left out and why, every bug a review found, and the table of deliberate divergences that differences from TanStack Query unpacks. How fidelity is proven explains how to read them.

See also

• How the examples are built, and the feature matrix for what is in and out.