Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

suspensive-react-query.md

135 lines5.2 KB

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 }
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
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)