https://peterbe.com

Peterbe.com - Stuff in Peter's headPeterbe.com is the personal website and blog of Peter Bengtsson.Peterbe.com - Stuff in Peter's headSkip to main navigationSkip to main contentSkip to searchPeterbe.comPeter Bengtsson's blogArchiveAboutContactSearchHow to handle success and failure in @tanstack/react-query useQuery hookSeptember 16, 20240 comments React, JavaScriptWhat @tanstack/react-query is is a fancy way of fetching data, on the client, in a React app. Simplified primer by example; instead of... function MyComponent() { const [userInfo, setUserInfo] = useState(null) useEffect(() => { fetch('/api/user/info') .then(response => response.json()) .then(data => { setUserInfo(data) }) }, []) return } you now do this: import { useQuery } from '@tanstack/react-query' function MyComponent() { const {data} = useQuery({ queryKey: ['userinfo'], queryFn: async () { const response = await fetch('/api/user/info') return response.json() } }) return } That's a decent start, but... Error handling is a thing. Several things can go wrong: Complete network failure during the fetch(...) Server being (temporarily) down Not authorized Backend URL not found Backend URL found but wrong parameters None of the code solutions above deal with these things. At least not all of them. By default, useQuery will retry if any error thrown inside that queryFn call. Queries that fail are silently retried 3 times, with exponential backoff delay before capturing and displaying an error to the UI. From the documentation about important defaults For example, if the server responds with a 403 the response body might not be of content-type JSON. So that response.json() might fail and throw and then useQuery will retry. You might be tempted to do this: queryFn: async () { const response = await fetch("/api/user/info") + if (!response.ok) { + throw new Error(`Fetching data failed with a ${response.status} from the server`) + } return response.json() } The problem with this is that useQuery still thinks it's an error and that it should retry. Sometimes it's the right thing to do, sometimes pointless. About retries The default implementation in @tanstack/react-query can be seen here: packages/query-core/src/retryer.ts In a gross simplification, it works like this: function run() { const promise = config.fn() Promise.resolve(promise) .then(resolve) .catch((error) => { if (shouldRetry(config)) { await sleep(config.sleepTime()) run() } else { reject(error) } }) I'm not being accurate here but the point is that it's quite simple. The config has stuff like a count of how many times it's retried previously, dynamically whether it should retry, and how long it should sleep. The point is that it doesn't care what the nature of the error was. It doesn't test if the error was of type Response or if error.message === "ECONNRESET" or something like that. So in a sense, it's a "dumping ground" for any error thrown. So if you look into the response, within your query function, and don't like the response, if you throw a new error, it will retry. And that might not be smart. In simple terms; you should retry if retrying is likely to yield a different result. For example, if the server responded with a 503 Service Unavailable it's quite possible that if you just try again, a little later, it'll work. What is wrong is if you get something like a 400 Bad Request response. Then, trying again won't work. Another thing that is wrong is if your own code throws an error within. For example, ... queryFn: async () { const response = await fetch('/api/user/info') const userInfo = response.json() await doSomethingComplexThatMightFail(userInfo) return userInfo } So, what's the harm? Suppose that you have something basic like this: queryFn: async () { const response = await fetch("/api/user/info") if (!response.ok) { throw new Error(`Fetching data failed with a ${response.status} from the server`) } return response.json() } and you use it like this: function MyComponent() { const {data, error} = useQuery(...) if (error) { return } if (!data) { return } return } then, I guess if it's fine to not be particularly "refined" about the error itself. It failed, refreshing the page might just work. If not an error, then what? The pattern I prefer, is to, if there is a problem with the response, to return it keyed as an error. Let's use TypeScript this time: // THIS IS THE NAIVE APPROACH type ServerResponse = { user: { first_name: string last_name: string } } ... function MyComponent() { const {data, error, isPending} = useQuery({ queryKey: ['userinfo'], queryFn: async () { const response = await fetch('/api/user/info') if (!response.ok) { throw new Error(`Bad response ${response.status}`) } const user = await response.json() return user } }) return

Username: {userInfo ? userInfo.user_name : not yet known}

} A better approach is to allow queryFn to return what it would 99% of the time, but also return an error, like this: // THIS IS THE MORE REFINED APPROACH type ServerResponse = { user?: { first_name: string last_name: string } errorCode?: number } ... function MyComponent() { const {data, error, isPending} = useQuery({ queryKey: ['userinfo'], queryFn: async () { const response = await fetch('/api/user/info') if (response.status >= 500) { // This will trigger useQuery to retry throw new Error(`Bad response ${response.status}`) } if (response.status >= 400) { return {errorCode: response.status} } const user = await response.json() return {user} } }) if (errorCode) { if (errorCode === 403) { return

You're not authorized. Log in here

} throw new Error(`Unexpected response from the API (${errorCode})`) } return

Username: {userInfo ? userInfo.user_name : not yet known}

} It's just an example, but the point is; that you treat "problems" as valid results. That way you avoid throwing errors inside the query function, which will trigger nice retries. And in this example, it can potentially throw an error in the rendering phase, outside the hook, which means it needs your attention (and does not deserve a retry) What's counter-intuitive about this is that your backend probably doesn't return the error optionally with the data. Your backend probably looks like this: # Example, Python, backend JSON endpoint def user_info_view(request): return JsonResponse({ "first_name": request.user.first, "last_name": request.user.last }) So, if that's how the backend responds, it'd be tempting to model the data fetched to that exact shape, but as per my example, you re-wrap it under a new key. Conclusion The shape of the data ultimately coming from within a useQuery function doesn't have to map one-to-one to how the server sends it. The advantage is that what you get back into the rendering process of your component is that there's a chance of capturing other types of errors that aren't retriable.Please post a comment if you have thoughts or questionsswr compared to @tanstack/react-queryAugust 30, 20240 comments JavaScriptI have a single-page-app built with React and Vite. It fetches data entirely on the client-side after it has started up. So there's no server at play other than the server that hosts the static assets. Until yesterday, the app was use swr to fetch data, now it's using @tanstack/react-query instead. Why? Because I'm curious. This blog post attempts to jot down some of the difference and contrasts. If you want to jump straight to the port diff, look at this commit: https://github.com/peterbe/analytics-peterbecom/pull/47/commits/eac4f873303bfb493320b0b4aa0f5f6ba133001a Bundle phobia When @tanstack/react-query first came out, back in the day when it was called React Query, I looked into it and immediately got scared how large it was. I think they've done some great work to remedy that because it's now not much larger than swr. Perhaps it's because swr, since wayback when, has grown too. When I run npm run build it spits this out: Before - with swr vite v5.4.2 building for production... ✓ 1590 modules transformed. dist/index.html 0.76 kB │ gzip: 0.43 kB dist/assets/index-CP2W9Ga1.css 0.41 kB │ gzip: 0.24 kB dist/assets/index-B8iHmcGS.css 196.05 kB │ gzip: 28.94 kB dist/assets/query-CvwMzO21.js 51.16 kB │ gzip: 18.61 kB dist/assets/index-ByNQKZOZ.js 79.45 kB │ gzip: 22.69 kB dist/assets/index-DnpwskLg.js 225.19 kB │ gzip: 72.76 kB dist/assets/BarChart-CwU8AXdH.js 397.99 kB │ gzip: 112.41 kB ❯ du -sh dist/assets 940K dist/assets After - with @tanstack/react-query vite v5.4.2 building for production... ✓ 1628 modules transformed. dist/index.html 0.76 kB │ gzip: 0.43 kB dist/assets/index-CP2W9Ga1.css 0.41 kB │ gzip: 0.24 kB dist/assets/index-B8iHmcGS.css 196.05 kB │ gzip: 28.94 kB dist/assets/query-CqpLJXAS.js 51.44 kB │ gzip: 18.71 kB dist/assets/index-BPszumoe.js 77.52 kB │ gzip: 22.14 kB dist/assets/index-DjC9VFZg.js 250.65 kB │ gzip: 78.88 kB dist/assets/BarChart-B-D1cgEG.js 400.24 kB │ gzip: 112.94 kB ❯ du -sh dist/assets 964K dist/assets In this case, it grew the total JS bundle by 26KB. As gzipped, it's 262.28 - 256.08 = 6.2 KB larger Provider necessary They work very similar, with small semantic differences (and of course features!) but one important difference is that when you use the useQuery hook (from import { useQuery } from "@tanstack/react-query") you first have to wrap the component in a provider. Like this: import { QueryClient, QueryClientProvider } from "@tanstack/react-query" import { Nav } from "./components/simple-nav" import { Routes } from "./routes" const queryClient = new QueryClient() export default function App() { return (