Skip to main content
Version: v10.0.0

HyperFetch vs SWR

SWR is Vercel's data fetching hook for React, and it is very good at one thing: showing cached data right away and refreshing it in the background. If you are looking for an swr alternative, it is worth knowing first what SWR does well, because for a lot of read-heavy React apps it is all you need.

This page compares SWR and HyperFetch on fetching, revalidation, mutations, realtime, offline and tooling. Claims about SWR link to its own docs.

What you'll learn
  1. How SWR's key and fetcher model compares to HyperFetch request objects.
  2. How revalidation defaults differ between the two.
  3. How mutations and subscriptions work in each.
  4. Where SWR sits next to React Query, and when to pick each library.

What SWR does well​

Vercel describes SWR as "a React Hooks library for data fetching". The name comes from stale-while-revalidate: return cached data first, then fetch fresh data and update.

  • Very little to learn. One hook, useSWR(key, fetcher), covers most reads. The key is usually the URL.
  • Fresh data by default. Per the API reference, revalidateOnFocus and revalidateOnReconnect are on, and identical requests within 2 seconds are deduplicated (dedupingInterval: 2000).
  • Mutations that refresh reads. useSWRMutation revalidates the matching useSWR data after the mutation resolves, and optimisticData with rollbackOnError covers optimistic UI. See the mutation docs.
  • Subscriptions. useSWRSubscription from swr/subscription (SWR 2.1.0 and later) feeds any realtime source into the same cache. See subscription.

If your app mostly reads data and your API calls are simple, SWR is a fine choice and you can stop reading here.


SWR react basics: key and fetcher​

The getting started page shows the core of swr react code:

import useSWR from "swr";

const fetcher = (...args) => fetch(...args).then((res) => res.json());

function Profile({ userId }) {
const { data, error, isLoading } = useSWR(`/api/user/${userId}`, fetcher);
}

The fetcher is yours. SWR calls it with the key and caches whatever it returns. That keeps SWR small and lets you use any HTTP client, but it also means request concerns live in your fetcher. With plain fetch, a 404 or 500 does not reject (see MDN), so error stays empty unless your fetcher checks res.ok and throws.

HyperFetch puts the request first. You describe it once with createRequest, and the built-in fetch adapter handles JSON, headers, timeouts and non-2xx errors:

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

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

export const getUser = client.createRequest<{ response: User; error: ApiError }>()({
endpoint: "/users/:userId",
});
import { useFetch } from "@hyper-fetch/react";

function Profile({ userId }: { userId: number }) {
const { data, error, loading } = useFetch(getUser.setParams({ userId }));
}

:userId in the endpoint becomes a required, typed param. A 404 lands in error typed as ApiError. Learn more in fetching and error handling.


Revalidation and refresh​

Both libraries serve cached data and refetch in the background. The defaults point in opposite directions:

OptionSWRHyperFetch
Refetch on window focusrevalidateOnFocus: truerefetchOnFocus: false
Refetch on reconnectrevalidateOnReconnect: truerefetchOnReconnect: false
PollingrefreshInterval, 0 (off)refresh: true with refreshTime
Deduplication2 second window by defaultOn for GET while the first call is in flight
Keep data while loadingkeepPreviousData: falsekeepPreviousData: "auto"
Retry on errorOn, errorRetryInterval: 5000Off, set retry and retryTime (or exponentialBackoff())

SWR assumes you want aggressive freshness. HyperFetch's useFetch refetches in the background on mount by default (revalidate: true, set it to false to trust the cache for its staleTime, 5 minutes by default), and lets you turn on focus and reconnect refetching per hook. Neither is wrong. Pick defaults that match how often your data changes. See refreshing and window focus.


Mutations​

SWR's useSWRMutation takes a key and a mutation function. Per the docs, the extra argument reaches the function "via the arg property of the 2nd parameter":

import useSWRMutation from "swr/mutation";

async function updateUser(url, { arg }) {
await fetch(url, { method: "POST", body: JSON.stringify(arg) });
}

function SaveButton() {
const { trigger, isMutating } = useSWRMutation("/api/user", updateUser);
return <button onClick={() => trigger({ name: "Ada" })}>Save</button>;
}

The neat part is that the key ties the mutation to the read: SWR revalidates useSWR("/api/user") when it is done.

In HyperFetch the mutation is another request, used with useSubmit:

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

const updateUser = client.createRequest<{ response: User; payload: { name: string } }>()({
endpoint: "/users/:userId",
method: "PATCH",
});

function SaveButton({ userId }: { userId: number }) {
const { submit, submitting, onSubmitSuccess } = useSubmit(updateUser.setParams({ userId }));

onSubmitSuccess(() => client.cache.invalidate(getUser.setParams({ userId })));

return <button onClick={() => submit({ payload: { name: "Ada" } })}>Save</button>;
}

You link the read and the write yourself with client.cache.invalidate(). In exchange the payload is typed, the body is serialized for you, and useSubmit reports upload and download progress. See submitting and cache revalidation.


Realtime​

useSWRSubscription is a thin bridge: you write a subscribe(key, { next }) function that opens your connection and calls next on each event. SWR shares one subscription per key across components.

HyperFetch ships the transport. The sockets package has WebSocket and SSE adapters, with typed listeners:

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

export const socket = createSocketClient({ url: "wss://api.example.com" });
export const onUserUpdated = socket.createListener<User>()({ topic: "user-updated" });

useListener(onUserUpdated) in React gives you data and the connection state.


Offline and queues​

SWR's revalidation docs cover refetching when the network comes back, and the API has refreshWhenOffline and isPaused(). They don't describe queueing writes made while offline.

HyperFetch requests go through a dispatcher. With the default offline: true, a request sent without a connection waits and is sent when the connection returns. queued: true sends them one at a time. Read offline and queueing.


Devtools​

SWR's devtools page points to SWRDevTools, a browser extension, and says it "is not an official project of Vercel".

HyperFetch has HyperFlow, a desktop app you connect with DevtoolsPlugin to inspect requests, cache and queues.


SWR vs React Query​

Most people searching this are choosing between SWR and TanStack Query, not HyperFetch. Both are server-state hooks that call a function you write. SWR keeps the API small and leans on revalidation. TanStack Query has more configuration, offline mutation persistence and an official devtools package. We cover TanStack Query on its own page: HyperFetch vs TanStack Query.


Side by side​

CapabilitySWRHyperFetch
Sends HTTP requestsNo, you write the fetcherYes, fetch adapter built in
Request definitionKey + fetchercreateRequest with typed params, payload and errors
ReadsuseSWRuseFetch
Writesmutate, useSWRMutationuseSubmit
Optimistic updatesoptimisticData, rollbackOnErrorsetOptimistic on the request
RealtimeuseSWRSubscription, your transport@hyper-fetch/sockets (WebSocket, SSE)
Offline write queueNot described in the docsYes
DevtoolsCommunity extensionHyperFlow
FrameworksReactReact

Which one fits you​

Stay on SWR when:

  • Your app is mostly reads, and focus and reconnect revalidation are what you want.
  • You already have a fetcher or SDK and only need caching on top.
  • You like a small API and are happy to keep request logic in your fetcher.

Pick HyperFetch when:

  • You want typed requests (params, payload, query params, errors) defined once and reused across components and tests.
  • Your app writes a lot: forms, uploads with progress, requests that must survive going offline.
  • You need sockets or SSE next to HTTP without a second library.
  • You want an SDK generated from your OpenAPI spec.
Summary
  • SWR caches what your fetcher returns and revalidates on focus and reconnect by default.
  • HyperFetch defines the request, sends it, and treats non-2xx responses as errors.
  • useSWRMutation refreshes reads by key. HyperFetch invalidates with client.cache.invalidate().
  • HyperFetch adds a socket transport, an offline queue and progress events.