Skip to main content
Version: v10.0.0

HyperFetch vs TanStack Query

TanStack Query (still called React Query by most people) is the market leader for server state in React. If you are looking for a tanstack query alternative, the first thing worth saying is that TanStack Query is a good library with a large community, long-lived docs and adapters for several frameworks. Plenty of teams should stay on it.

This page compares the two on the tasks you actually do every day: defining a request, caching it, mutating data, handling realtime and offline, and debugging. Every TanStack Query claim links to its own docs.

What you'll learn
  1. How query keys and query functions differ from typed request objects.
  2. How caching, invalidation and mutations look in each library.
  3. What each one gives you for realtime, offline and devtools.
  4. When to pick a React Query alternative, and when not to.

What TanStack Query does well​

  • It works with any async function. Its overview shows a queryFn that you write. fetch, Axios, a GraphQL client or an SDK all work, because TanStack Query only cares about the promise.
  • Sensible defaults for freshness. Per its important defaults, data is stale right away and refetched when a new instance mounts, the window is refocused or the network reconnects. Failed queries are retried 3 times with exponential backoff.
  • Offline mutations. Mutations can be persisted and resumed, and failed mutations are retried in order when the device reconnects.
  • Several frameworks. The repository README lists React Query, Solid Query, Svelte Query and Vue Query.

If your team already knows it and it does what you need, there is no reason to move.


Defining a request​

This is the biggest difference between the two.

TanStack Query identifies data by a query key. Its query keys guide says keys "have to be an Array at the top level" and must be unique to the data. The request itself lives in the query function, usually written inline or in a helper:

import { useQuery } from "@tanstack/react-query";

function Todos() {
const { data, isPending, error } = useQuery({
queryKey: ["todos"],
queryFn: async () => {
const response = await fetch("/api/todos");
if (!response.ok) throw new Error("Request failed");
return response.json();
},
});
}

HyperFetch defines the request once, outside components, with createRequest. The object holds the endpoint, the method and the types. The cache key is derived from it, so you never write one by hand:

import { createClient } from "@hyper-fetch/core";

export const client = createClient({ url: "https://api.example.com" });

export const getTodos = client.createRequest<{ response: Todo[] }>()({
endpoint: "/todos",
});

export const createTodo = client.createRequest<{ response: Todo; payload: { title: string } }>()({
endpoint: "/todos",
method: "POST",
});
import { useFetch } from "@hyper-fetch/react";

function Todos() {
const { data, loading, error } = useFetch(getTodos);
}

The same getTodos works outside React with getTodos.send(), which resolves with { data, error, status } instead of throwing. Non-2xx responses land in error, so there is no response.ok check to forget. Types for payload, query params, URL params (:todoId in the endpoint becomes a required param) and errors live on the request. See requests for the full set.

The trade-off: TanStack Query's approach drops into any codebase. HyperFetch asks you to describe your API first, and pays you back with less glue code and one place to change an endpoint.


Caching and invalidation​

Both libraries cache per key, serve cached data while refetching in the background, and let you mark data stale.

BehaviourTanStack QueryHyperFetch
Cache identityQuery key you writecacheKey derived from the request
Stale by defaultImmediatelyAfter staleTime, 5 minutes by default
Refetch on mountWhen stale, so on every new mount by defaultOn by default (revalidate: true in useFetch)
Unused data removedAfter 5 minutes (gcTime)After cacheTime, 5 minutes by default
Refetch on window focusOn by defaultOff by default, refetchOnFocus: true
Refetch on reconnectOn by defaultOff by default, refetchOnReconnect: true
Retries on failure3, exponential backoff0 by default, set retry, retryTime: exponentialBackoff() for backoff
InvalidatequeryClient.invalidateQueries({ queryKey })client.cache.invalidate(request), a string or a RegExp

TanStack Query invalidates through the query client, by query key. In HyperFetch you pass the request itself, a cache key string or a RegExp, and any mounted useFetch for that key fetches again. Details are in cache revalidation.


Mutations: useMutation vs useSubmit​

TanStack Query's invalidation example pairs useMutation with the query client:

const queryClient = useQueryClient();

const mutation = useMutation({
mutationFn: addTodo,
onSuccess: async () => {
await queryClient.invalidateQueries({ queryKey: ["todos"] });
},
});

mutation.mutate({ title: "Buy milk" });

useMutation returns mutate, mutateAsync (a promise that throws on error) and isPending.

HyperFetch uses useSubmit with a request you already defined:

import { useSubmit } from "@hyper-fetch/react";

function AddTodo() {
const { submit, submitting, onSubmitSuccess } = useSubmit(createTodo);

onSubmitSuccess(() => {
client.cache.invalidate(getTodos);
});

return (
<button disabled={submitting} onClick={() => submit({ payload: { title: "Buy milk" } })}>
Add
</button>
);
}

submit returns a promise of the response and never throws, so const { data, error } = await submit(...) is enough. useSubmit also exposes upload and download progress (onSubmitUploadProgress, onSubmitDownloadProgress). More in submitting and optimistic updates.


Realtime​

TanStack Query doesn't open connections. It runs the functions you give it. For WebSockets you open the socket yourself and write incoming messages into the cache with setQueryData or invalidateQueries. That works well and keeps TanStack Query small.

HyperFetch ships a sockets package with WebSocket and Server-Sent Events adapters. Listeners and emitters are typed and defined the same way as HTTP requests:

import { createSocketClient } from "@hyper-fetch/sockets";

export const socket = createSocketClient({ url: "wss://api.example.com" });

export const onTodoAdded = socket.createListener<Todo>()({ topic: "todo-added" });

// Refresh the list whenever the server announces a new todo
onTodoAdded.listen(() => {
client.cache.invalidate(getTodos);
});

In React, useListener(onTodoAdded) returns data and connection state. See useListener.


Offline queueing​

TanStack Query's network mode defaults to online, where queries and mutations "will not fire unless you have network connection" and show a paused fetch status. Paused mutations can be persisted, but per the mutations guide they "cannot be resumed when the page is reloaded unless you provide a default mutation function" with setMutationDefaults.

HyperFetch sends every request through a dispatcher queue. Requests have offline: true by default, so a request made while offline waits and goes out when the connection returns. Set queued: true to send them one by one. The queue can be persisted to a storage you provide, and a lazyStorage (IndexedDB, AsyncStorage) is read back and sent on the next start. Stored requests are rebuilt into request instances, so there is no mutation function to re-register after a restart. Functions on a request, like mappers or a function retryTime, are not stored. The docs recommend persistent queues for single-instance apps like React Native, since several browser tabs sharing one queue can send duplicates. See offline, queueing and persistence.


Adapters​

TanStack Query has no adapters because it doesn't send requests. Whatever client you use in the queryFn is your adapter.

HyperFetch's client has one adapter, and every request goes through it. The default uses fetch. You can switch to Axios, GraphQL or Firebase with client.setAdapter(), and your requests and hooks don't change.


Devtools​

TanStack Query has React Query Devtools, a separate @tanstack/react-query-devtools package rendered inside your app. It is only bundled when NODE_ENV is development by default.

HyperFetch's devtools are HyperFlow, a desktop app for macOS, Windows and Linux. You connect a client with DevtoolsPlugin from @hyper-fetch/plugin-devtools, then inspect requests, browse and edit the cache, and pause or resume queues.


Framework support​

This is a clear win for TanStack Query. It has official adapters for React, Solid, Svelte and Vue.

HyperFetch's UI bindings are React only (@hyper-fetch/react), including React Native and Electron. The core package runs anywhere JavaScript runs, so requests work in Node or plain TypeScript without hooks.


Side by side​

CapabilityTanStack QueryHyperFetch
Sends HTTP requestsNo, you write the queryFnYes, fetch adapter built in
Request definitionQuery key + query functioncreateRequest object with types
MutationsuseMutationuseSubmit
RealtimeBring your own socket@hyper-fetch/sockets (WebSocket, SSE)
Offline mutationsYes, with persistence setupYes, through the request queue
Upload progressUp to your queryFnYes, with the Axios adapter in browsers
DevtoolsIn-app panelHyperFlow desktop app
FrameworksReact, Solid, Svelte, VueReact
Normalized cacheNoNo

SWR vs React Query​

If you are weighing SWR vs React Query rather than HyperFetch, the short version: SWR is smaller and focused on reads with useSWR, with writes through mutate and useSWRMutation. TanStack Query has more knobs, offline mutation persistence and official devtools. Our HyperFetch vs SWR page covers SWR in detail.


Which one fits you​

Stay on TanStack Query when:

  • You use Vue, Solid or Svelte, or share code across several frameworks.
  • You already have an HTTP client or SDK and only want caching on top of it.
  • Your team knows it well and you don't need realtime or upload progress from the same library.

Pick HyperFetch when:

  • You want each endpoint defined once, with its types, and used the same way in React, in Node and in tests.
  • You need WebSockets or SSE next to HTTP without wiring a second library.
  • Offline matters: requests sent offline should wait, queue in order and survive a reload.
  • You want upload progress, queues you can pause, and a typed SDK generated from OpenAPI.
Summary
  • TanStack Query caches the result of functions you write. HyperFetch defines and sends the request too.
  • Invalidation: invalidateQueries({ queryKey }) vs client.cache.invalidate(request).
  • Mutations: useMutation vs useSubmit, which never throws and reports progress.
  • HyperFetch adds sockets and an offline request queue. TanStack Query adds more frameworks.