Open History to see the last commit
1---
2id: suspensive-react-query
3title: Suspensive React Query
4---
5β
6Typesafe useQuery, useQueries, useInfiniteQuery with default suspense option.
7β
8Use @suspensive/react-query, delegate loading and error handling to the outside of the component with [useSuspenseQuery](https://suspensive.org/docs/react-query/useSuspenseQuery), [useSuspenseQueries](https://suspensive.org/docs/react-query/useSuspenseQueries) and [useSuspenseInfiniteQuery](https://suspensive.org/docs/react-query/useSuspenseInfiniteQuery), and focus on success inside the component.
9β
10You don't even need to use the isSuccess flag.
11β
12## Installation
13β
14You can install @suspensive/react-query via [NPM](https://www.npmjs.com/package/@suspensive/react-query).
15β
16```bash
17npm i @suspensive/react-query
18```
19β
20or
21β
22```bash
23pnpm add @suspensive/react-query
24```
25β
26or
27β
28```bash
29yarn add @suspensive/react-query
30```
31β
32### Motivation
33β
34If you turn suspense mode on in @tanstack/react-query, You can use useQuery with Suspense and ErrorBoundary.
35β
36```tsx
37import { useQuery } from '@tanstack/react-query'
38β
39const Example = () => {
40 const query = useQuery({
41 queryKey,
42 queryFn,
43 suspense: true,
44 })
45β
46 query.data // TData | undefined
47β
48 if (query.isSuccess) {
49 query.data // TData
50 }
51}
52```
53β
54Typically query.data will be `TData | undefined` like this code example.
55But actual useQuery's return type:query.data will be always fulfilled because of [Suspense](https://suspensive.org/docs/react/Suspense) and [ErrorBoundary](https://suspensive.org/docs/react/ErrorBoundary) as parent of this component.
56β
57This is why @suspensive/react-query provide **useSuspenseQuery**
58β
59## useSuspenseQuery
60β
61Return type of this hook have no isLoading, isError property. because Suspense and ErrorBoundary will guarantee this hook's data.
62β
63In addition, this hook's options have default suspense: true. and you can provide new options to this hook like useQuery of @tanstack/react-query.
64β
65```tsx
66import { useSuspenseQuery } from '@suspensive/react-query'
67β
68const Example = () => {
69 const query = useSuspenseQuery({
70 queryKey,
71 queryFn,
72 }) // suspense:true is default.
73β
74 // No need to do type narrowing by isSuccess
75 query.data // TData
76}
77```
78β
79### Concentrate on only Success
80β
81Now, we can concentrate component as any fetching will be always success in component.
82β
83## queryOptions
84β
85Tkdodo, The maintainer of TanStack Query explains well why this interface is needed in [video explaining queryOptions in TanStack Query v5](https://youtu.be/bhE3wuB_TuA?feature=shared&t=1697).
86You can also use queryOptions in TanStack Query v4.
87β
881. QueryKey management becomes easier by processing queryKey and queryFn together.
892. You can remove unnecessary custom query hooks. This is because they can all be used directly in `useQuery`, `useQueries` of TanStack Query v4.
903. TanStack Query v5 already supports queryOptions. This Suspensive React Query's `queryOptions` will make migration from TanStack Query v4 to TanStack Query v5 easier.
91β
92```tsx
93import { queryOptions } from '@suspensive/react-query'
94import { useQuery, useQueries, useQueryClient } from '@tanstack/react-query'
95β
96const postQueryOptions = (postId) =>
97 queryOptions({
98 queryKey: ['posts', postId] as const,
99 queryFn: ({
100 queryKey: [, postId], // You can use queryKey.
101 }) => fetch(`https://example.com/posts/${postId}`),
102 })
103β
104// No need to create custom query hooks.
105// You can use queryOptions directly in useQuery, useQueries.
106const post1Query = useQuery(postQueryOptions(1))
107β
108const [post1Query, post2Query] = useQueries({
109 queries: [
110 postQueryOptions(1),
111 { ...postQueryOptions(2), refetchInterval: 2000 },
112 ],
113})
114β
115// You can easily use queryKey and queryFn in queryClient's methods.
116const queryClient = useQueryClient()
117queryClient.refetchQueries(postQueryOptions(1))
118queryClient.prefetchQuery(postQueryOptions(1))
119queryClient.invalidateQueries(postQueryOptions(1))
120queryClient.fetchQuery(postQueryOptions(1))
121queryClient.resetQueries(postQueryOptions(1))
122queryClient.cancelQueries(postQueryOptions(1))
123```
124β
125### Using queryOptions in TanStack Query v4
126β
127> "One of the best ways to share queryKey and queryFn between multiple places, yet keep them co-located to one another, is to use the queryOptions helper." For more details, you can refer to the [TanStack Query v5 Official Docs - Query Options](https://tanstack.com/query/v5/docs/framework/react/guides/query-options).
128β
129You can use queryOptions in TanStack Query v4 just like in TanStack Query v5, and it is fully compatible with the TanStack Query v4 API.
130β
131### useSuspenseQuery is Official API now! (from v5)
132β
133@suspensive/react-query provides not only [useSuspenseQuery](https://suspensive.org/docs/react-query/useSuspenseQuery), also [useSuspenseQueries](https://suspensive.org/docs/react-query/useSuspenseQueries), [useSuspenseInfiniteQuery](https://suspensive.org/docs/react-query/useSuspenseInfiniteQuery). From @tanstack/react-query v5 provides [official public hook apis for suspense](https://tanstack.com/query/v5/docs/react/guides/suspense) like @suspensive/react-query's hooks. If want to use them early in v4, use this @suspensive/react-query first.
134β
135Check the complete documentation on [Suspensive Official Docs Site](https://suspensive.org/) and also welcome Pull Request on [Suspensive GitHub](https://github.com/suspensive/react)