Migrating from React Query (TanStack Query)
TanStack Query caches the result of any async function you give it. You pick a queryKey, write a queryFn that calls
fetch, and useQuery keeps the result in sync. Migrating from react query to HyperFetch moves that work into the
request itself: a request knows its endpoint, method, params and types, and its cache key comes from those values. Hooks
take the request instead of a key and a function.
This page maps every TanStack Query concept you are likely using to its HyperFetch counterpart, lists what has no counterpart, and then moves one small feature over with before and after code.
- How
useQuery,useMutationand query keys map touseFetch,useSubmitand cache keys. - Which defaults differ (
staleTime,gcTime, retries, refetch on focus) and how to match them. - How to replace
invalidateQueriesand React Query Devtools. - What has no equivalent in HyperFetch.
Should you migrate at all?
TanStack Query is a good library. It works with any async function, so it caches database reads, third-party SDK calls
and fetch calls alike. It has a large community, a lot of answered questions, and a mature server rendering story,
including streaming pending queries from
the server. If your app is happy on it, stay.
HyperFetch is worth the move when you also want the parts TanStack Query leaves to you: typed request definitions, one place for headers and auth, request queues, offline replay, upload and download progress, sockets with the same API, and an SDK generated from OpenAPI. Both libraries can run side by side while you move screen by screen. They don't share a cache, so a screen should read a given resource through one of them.
The mental model in one example
// TanStack Query: you own the key and the fetch function
const { data } = useQuery({
queryKey: ["todos", todoId],
queryFn: () => fetch(`/api/todos/${todoId}`).then((res) => res.json()),
});
// HyperFetch: the request is defined once, the key is derived from it
const getTodo = client.createRequest<{ response: Todo }>()({ endpoint: "/todos/:todoId" });
const { data } = useFetch(getTodo.setParams({ todoId }));
The second useFetch call with the same params reads the same cache entry. You never write ["todos", todoId]. The
cache key is built from the method, the endpoint with its params filled in, and the query params. Override it with
setCacheKey() when you need to.
Concept mapping
Every TanStack name below comes from the useQuery, useMutation and QueryClient references.
| TanStack Query | HyperFetch | Notes |
|---|---|---|
QueryClient + QueryClientProvider | createClient({ url }) | Requests carry their client, so no provider is required |
defaultOptions on the QueryClient | <Provider config={{ useFetchConfig }}> | Default hook options for the tree |
useQuery({ queryKey, queryFn }) | useFetch(request) | Runs on mount and when the request (params, query params) changes |
useMutation({ mutationFn }) | useSubmit(request) | submit() returns a promise with { data, error }, no mutate / mutateAsync split |
queryKey | request.cacheKey | Derived automatically, setCacheKey() to override |
queryClient.invalidateQueries({ queryKey }) | client.cache.invalidate(request | key | RegExp) | Marks entries stale, mounted useFetch hooks refetch |
queryClient.setQueryData | client.cache.update(request, updater) | Does nothing when there is no entry yet |
queryClient.getQueryData | request.read() | Reads the cached response |
staleTime (default: stale immediately) | staleTime / setStaleTime() (default 5 minutes) | Set on the request, not on the hook |
gcTime (default 5 minutes) | cacheTime / setCacheTime() (default 5 minutes) | Counted from when the response was stored, see below |
enabled: false | disabled: true | Inverted flag |
select | select | Same idea, the cache stays shared |
placeholderData, initialData | initialResponse | Used by the hook while the cache is empty |
refetchInterval | refresh: true + refreshTime | |
refetchOnWindowFocus (on by default) | refetchOnFocus (off by default) | |
refetchOnReconnect | refetchOnReconnect (off by default) | |
retry (3 by default), retryDelay | retry / setRetry() (0 by default), retryTime (500 ms) | Set on the request. retryTime also takes a function, like exponentialBackoff() |
throwOnError | throwOnError | Sends the error to the nearest Error Boundary |
useSuspenseQuery | useFetch(request, { suspense: true }) | Suspends until the data arrives |
useInfiniteQuery | useInfiniteFetch(request, { pagination }) | No getNextPageParam, you name the paging fields |
useIsFetching | useIsFetching(client) | Filter with queryKey or predicate |
onMutate for optimistic updates | request.setOptimistic() | Rollback is declared next to the change |
dehydrate + HydrationBoundary | request.dehydrate() + Hydrate | See Data fetching in Next.js |
| React Query Devtools | HyperFlow + DevtoolsPlugin | Desktop app instead of an in-page panel |
useQueries | Not built in | See What has no equivalent |
Defaults that behave differently
Copying your hooks one to one gives you different timing, because the defaults differ. TanStack's important defaults treat cached data as stale right away, retry failed queries 3 times, and refetch stale queries on mount, window focus and reconnect.
HyperFetch requests default to staleTime and cacheTime of 5 minutes and retry: 0. On the hook side, useFetch
defaults to revalidate: true, which refetches in the background on every mount even when the cache is fresh.
refetchOnFocus and refetchOnReconnect are off.
To get close to TanStack's behaviour:
import { Provider } from "@hyper-fetch/react";
// Refetch when the tab gets focus or the network comes back, for every useFetch in the tree
export const App = () => (
<Provider config={{ useFetchConfig: { refetchOnFocus: true, refetchOnReconnect: true } }}>
<Routes />
</Provider>
);
Retries live on the request: getTodos.setRetry(3). The delay between attempts is a fixed 500 ms by default. For a
delay that grows with every attempt, pass setRetryTime(exponentialBackoff()), exported from @hyper-fetch/core. If you used staleTime to skip refetches, set it on the request
and pass revalidate: false to the hook, so useFetch only fetches when the cached data is stale.
Two more differences are worth knowing:
cacheTimeis notgcTime. TanStack starts thegcTimetimer when the last observer unmounts. HyperFetch countscacheTimefrom the moment the response is stored, andclient.cache.update()restarts it.- Deduplication depends on the method. TanStack shares one promise between identical queries. In HyperFetch, the
default HTTP adapter deduplicates
GETrequests already, so identical reads in flight share one network call. For other methods it is opt-in withsetDeduplicate(true), and an explicitdeduplicateoption always wins.
Step-by-step: migrating a to-do list
The feature: a list of to-dos, a button that adds one, and the list refreshing after the add.
Before: TanStack Query
import { QueryClient, QueryClientProvider, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
type Todo = { id: number; title: string };
const queryClient = new QueryClient();
const fetchTodos = async (): Promise<Todo[]> => {
const res = await fetch("/api/todos");
if (!res.ok) throw new Error("Could not load to-dos");
return res.json();
};
const createTodo = async (title: string): Promise<Todo> => {
const res = await fetch("/api/todos", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ title }),
});
if (!res.ok) throw new Error("Could not add the to-do");
return res.json();
};
function Todos() {
const queryClient = useQueryClient();
const { data, isPending, error } = useQuery({ queryKey: ["todos"], queryFn: fetchTodos, staleTime: 30_000 });
const addTodo = useMutation({
mutationFn: createTodo,
onSuccess: () => queryClient.invalidateQueries({ queryKey: ["todos"] }),
});
if (isPending) return <p>Loading...</p>;
if (error) return <p>{error.message}</p>;
return (
<div>
<ul>{data.map((todo) => <li key={todo.id}>{todo.title}</li>)}</ul>
<button disabled={addTodo.isPending} onClick={() => addTodo.mutate("Write the docs")}>
Add
</button>
</div>
);
}
export const App = () => (
<QueryClientProvider client={queryClient}>
<Todos />
<ReactQueryDevtools initialIsOpen={false} />
</QueryClientProvider>
);
1. Install the packages
npm install @hyper-fetch/core @hyper-fetch/react
2. Replace the fetch functions with requests
The client holds the base URL. Each request replaces a queryFn or mutationFn, and its types replace the
Promise<Todo[]> annotations. JSON encoding and the res.ok check are done by the adapter: a non-2xx response comes
back as error, and send() resolves instead of throwing.
import { createClient, Time } from "@hyper-fetch/core";
type Todo = { id: number; title: string };
export const client = createClient({ url: "http://localhost:3000/api" });
export const getTodos = client
.createRequest<{ response: Todo[] }>()({ endpoint: "/todos" })
.setStaleTime(30 * Time.SEC);
export const createTodo = client.createRequest<{ response: Todo; payload: { title: string } }>()({
endpoint: "/todos",
method: "POST",
});
3. Swap the hooks
import { useFetch, useSubmit } from "@hyper-fetch/react";
import { client, createTodo, getTodos } from "./api";
export function Todos() {
const { data, isPending, error } = useQuery({ queryKey: ["todos"], queryFn: fetchTodos, staleTime: 30_000 });
const { data, loading, error } = useFetch(getTodos);
const { submit, submitting, onSubmitSuccess } = useSubmit(createTodo);
onSubmitSuccess(() => client.cache.invalidate(getTodos));
if (loading) return <p>Loading...</p>;
if (error) return <p>Could not load to-dos</p>;
return (
<div>
<ul>{data?.map((todo) => <li key={todo.id}>{todo.title}</li>)}</ul>
<button disabled={submitting} onClick={() => submit({ payload: { title: "Write the docs" } })}>
Add
</button>
</div>
);
}
client.cache.invalidate(getTodos) marks the /todos entry stale, and the mounted useFetch refetches it. For
TanStack's prefix matching (["todos"] also matching ["todos", 1]), pass a RegExp:
client.cache.invalidate(/\/todos/) invalidates every cached entry whose key contains /todos.
If the server returns the new item, you can skip the refetch and patch the list instead:
onSubmitSuccess(({ response }) => {
client.cache.update(getTodos, (previous) => ({ data: [...(previous?.data ?? []), response.data] }));
});
For updates that show before the server answers, move the logic to the request with
setOptimistic().
4. Replace React Query Devtools
React Query Devtools is a component you render in the page, and it is left out of production builds. The HyperFetch counterpart is HyperFlow, a desktop app for macOS, Windows and Linux. Your app streams requests, cache and queue events to it through a plugin:
import { DevtoolsPlugin } from "@hyper-fetch/plugin-devtools";
if (process.env.NODE_ENV === "development") {
client.addPlugin(DevtoolsPlugin({ appName: "Todos" }));
}
The connecting guide covers installing the plugin and checking the connection.
5. Remove the provider
export const App = () => (
<QueryClientProvider client={queryClient}>
<Todos />
<ReactQueryDevtools initialIsOpen={false} />
</QueryClientProvider>
);
export const App = () => <Todos />;
Add the HyperFetch Provider only if you want different hook defaults for the tree. Once the last useQuery is gone,
uninstall @tanstack/react-query and @tanstack/react-query-devtools.
Suspense and infinite lists
useSuspenseQuery becomes the suspense option. Wrap the component in a Suspense boundary as before:
const { data } = useFetch(getTodos, { suspense: true });
useInfiniteQuery needs initialPageParam and getNextPageParam, and you flatten data.pages yourself.
useInfiniteFetch takes the names of the paging fields instead and returns a flat items list:
const { items, hasNextPage, isFetchingNextPage, fetchNextPage } = useInfiniteFetch(getFeed, {
pagination: { cursor: "cursor", next: "nextCursor", items: "data" },
});
Page numbers, offsets and cursors are covered in the infinite scroll guide and the
useInfiniteFetch reference.
What has no equivalent
Some TanStack Query features have no direct counterpart. Plan for these before you start:
useQueries. There is no hook that takes a dynamic list of requests. CalluseFetchonce per request when the number is fixed, or render a child component per item that callsuseFetchitself.- Caching any async function. A
queryFncan read IndexedDB or call a vendor SDK. HyperFetch caches requests sent through an adapter. For a non-HTTP source, write an adapter for it. gcTimecounted from the last unmount.cacheTimestarts when the response is stored, as described above.- Streaming pending queries from the server.
request.dehydrate()captures finished responses only. - An in-page devtools panel. HyperFlow runs as a separate app.
useQuerybecomesuseFetch(request)anduseMutationbecomesuseSubmit(request).- Query keys disappear: the cache key comes from the request, and
client.cache.invalidate()replacesinvalidateQueries. - Defaults differ: stale time 5 minutes, no retries, no refetch on focus. Set them on the request or in
Provider. - React Query Devtools becomes HyperFlow with
DevtoolsPlugin. useQueries, caching arbitrary async functions and streaming pending queries have no direct equivalent.
Next, read the useFetch guide, the useSubmit guide and the
cache reference.
