TanStack Query (React Query) Essentials

1
2
npm i @tanstack/react-query
npm i -D @tanstack/eslint-plugin-query 

1
2
3
4
5
import tanstackQuery from '@tanstack/eslint-plugin-query'

export default [
  ...tanstackQuery.configs['flat/recommended']
]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import {
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'
import DelayedData from '@/components/DelayedData'

const queryClient = new QueryClient()

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <DelayedData />
    </QueryClientProvider>
  )
}

1
const result = useQuery<DataType>(options)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { useQuery } from '@tanstack/react-query'

type ResponseValue = {
  message: string
  time: string
}

export default function DelayedData() {
  const { data } = useQuery<ResponseValue>({
    queryKey: ['delay'],
    queryFn: async () => (await fetch('https://api.heropy.dev/v0/delay?t=1000')).json(),
    staleTime: 1000 * 10 // 10 seconds
  })
  return <div>{data?.time}</div>
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Single-item query key
useQuery({ queryKey: ['hello'] })

// Multi-item query key
useQuery({ queryKey: ['hello', 'world', 123, { a: 1, b: 2 }] })

// The same query
useQuery({ queryKey: ['hello', 'world', 123, { a: 1, b: 2 }] })
useQuery({ queryKey: ['hello', 'world', 123, { b: 2, c: undefined, a: 1 }] })

// Different queries
useQuery({ queryKey: ['hello', 'world', 123, { a: 1, b: 2 }] })
useQuery({ queryKey: ['hello', 'world', 123, { a: 1, b: 2, c: 3 }] })
useQuery({ queryKey: ['hello', 'world'] })
useQuery({ queryKey: [123, 'world', { a: 1, b: 2, c: 3 }, 'hello'] })

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { useQuery } from '@tanstack/react-query'

type ResponseValue = {
  message: string
  time: string
}

export default function DelayedData({ wait = 1000 }: { wait?: number }) {
  const { data } = useQuery<ResponseValue>({
    queryKey: ['delay', wait],
    queryFn: async () => (await fetch(`https://api.heropy.dev/v0/delay?t=${wait}`)).json(),
    staleTime: 1000 * 10
  })
  return <div>{data?.time}</div>
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import DelayedData from '@/components/DelayedData'

const queryClient = new QueryClient()

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <DelayedData />
      <DelayedData wait={2000} />
      <DelayedData wait={3000} />
    </QueryClientProvider>
  )
}

1
2
3
4
5
6
7
8
9
10
// ...
export default function DelayedData({ wait = 1000 }: { wait?: number }) {
  // eslint-disable-next-line @tanstack/query/exhaustive-deps
  const { data } = useQuery<ResponseValue>({ // ESLint Error - The following dependencies are missing in your queryKey: wait
    queryKey: ['delay'],
    queryFn: async () => (await fetch(`https://api.heropy.dev/v0/delay?t=${wait}`)).json(),
    staleTime: 1000 * 10
  })
  return <div>{data?.time}</div>
}

1
2
3
4
5
6
7
8
9
10
import tanstackQuery from '@tanstack/eslint-plugin-query'

export default [
  ...tanstackQuery.configs['flat/recommended'],
  {
    rules: {
      '@tanstack/query/exhaustive-deps': 'off'
    }
  }
]

1
2
3
4
5
6
7
8
9
10
import tanstackQuery from '@tanstack/eslint-plugin-query'

export default [
  ...tanstackQuery.configs['flat/recommended'],
  {
    rules: {
      '@tanstack/query/exhaustive-deps': ['error', { allowlist: { variables: ['wait'] } }]
    }
  }
]

1
2
3
4
useQuery({
  queryKey: ['users'],
  queryFn: async ({ signal }) => (await fetch('https://api.heropy.dev/v0/users', { signal })).json()
})

1
2
3
4
5
useQuery({
  queryKey: ['users'],
  queryFn: async ({ signal }) =>
    (await axios.get('https://api.heropy.dev/v0/users', { signal })).data
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
import { useQuery } from '@tanstack/react-query'

type ResponseValue = {
  message: string
  time: string
}

export default function DelayedData() {
  const { data, error } = useQuery<ResponseValue>({
    queryKey: ['delay'],
    queryFn: async () => {
      const res = await fetch('https://api.heropy.dev/v0/delay?t=1000')
      const data = await res.json()
      if (!data.time) {
        throw new Error('Something went wrong!')
      }
      return data
    },
    staleTime: 1000 * 10,
    retry: 1
  })
  return (
    <>
      {data && <div>{JSON.stringify(data)}</div>}
      {error && <div>{error.message}</div>}
    </>
  )
}

1
2
3
4
5
6
7
8
// fetchUser(id: string): Promise<User>
const [userId, setUserId] = useState<string>() // string | undefined

useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId!), // Without the assertion (!), you get a 'string | undefined' type error!
  enabled: Boolean(userId)
})

1
2
3
4
5
6
import { useQuery, skipToken } from '@tanstack/react-query'

useQuery({
  queryKey: ['user', userId],
  queryFn: userId ? () => fetchUser(userId) : skipToken // userId is a string!
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import { useQuery } from '@tanstack/react-query'

type Users = User[]
interface User {
  id: string
  name: string
  age: number
}

export default function UserNames() {
  const { data } = useQuery<Users, Error, string[]>({
    queryKey: ['users'],
    queryFn: async () => {
      const res = await fetch('https://api.heropy.dev/v0/users')
      const { users } = await res.json()
      return users
    },
    staleTime: 1000 * 10,
    select: data => data.map(user => user.name)
  })
  return (
    <>
      <h2>User Names</h2>
      <ul>{data?.map((name, i) => <li key={i}>{name}</li>)}</ul>
    </>
  )
}

1
2
3
4
5
6
7
8
9
useQuery({
  queryKey: ['users'],
  queryFn: async (): Promise<Users> => {
    const res = await fetch('https://api.heropy.dev/v0/users')
    const { users } = await res.json()
    return users
  },
  select: data => data.map(user => user.name)
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// ...

export default function Movies() {
  // ...
  
  const { data: movies } = useQuery<Movie[]>({
    queryKey: ['movies', searchText], // Search term
    queryFn: async () => {
      const res = await fetch(`https://omdbapi.com?apikey=7035c60c&s=${searchText}`)
      const { Search: movies } = await res.json()
      return movies
    },
    placeholderData: prev => prev
  })
  
  // ...
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// ...
import {
  QueryClient,
  QueryClientProvider,
  QueryCache
} from '@tanstack/react-query'

const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (_error, query) => {
      alert(query.meta?.myErrorMessage) // Show the error message!
    }
  })
})

// ...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// ...

export default function Movies() {
  // ...
  
  const { data: movies } = useQuery<Movie[]>({
    queryKey: ['movies', searchText], // Search term
    queryFn: async () => {
      const res = await fetch(`https://omdbapi.com?apikey=7035c60c&s=${searchText}`)
      const { Search: movies } = await res.json()
      return movies
    },
    meta: {
      myErrorMessage: 'Unable to search for movies!'
    }
  })
  
  // ...
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// ...

export default function DelayedData() {
  const { data, isFetching, isPending, isLoading } = useQuery<ResponseValue>({
    queryKey: ['delay'],
    queryFn: async () => (await fetch('https://api.heropy.dev/v0/delay?t=1000')).json(),
    staleTime: 1000 * 10
  })
  return (
    <>
      <div>isFetching: {JSON.stringify(isFetching)}</div>
      <div>isPending: {JSON.stringify(isPending)}</div>
      <div>isLoading: {JSON.stringify(isLoading)}</div>
      <div>{data?.time}</div>
    </>
  )
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
import { useQuery } from '@tanstack/react-query'

type ResponseValue = {
  message: string
  time: string
}

export default function DelayedData() {
  const { data, isStale, isFetching, isLoading, refetch } =
    useQuery<ResponseValue>({
      queryKey: ['delay'],
      queryFn: async () => (await fetch('https://api.heropy.dev/v0/delay?t=1000')).json(),
      staleTime: 1000 * 10
    })
  return (
    <>
      {isLoading ? (
        <div>Loading..</div>
      ) : (
        <>
          <div>{data?.time}</div>
          <div>Is the data stale?: {JSON.stringify(isStale)}</div>
          <button
            disabled={isFetching}
            onClick={() => refetch()}>
            {isFetching ? 'Fetching data..' : 'Refetch data!'}
          </button>
        </>
      )}
    </>
  )
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// ...

export default function DelayedData() {
  const { data, isStale, refetch } = useQuery<ResponseValue>({
    queryKey: ['delay'],
    queryFn: async () => (await fetch('https://api.heropy.dev/v0/delay?t=1000')).json(),
    staleTime: 1000 * 10
  })
  return (
    <>
      <div>{data?.time}</div>
      <div>Is the data stale?: {JSON.stringify(isStale)}</div>
      <button onClick={() => refetch()}>Fetch data!</button>
    </>
  )
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import { useQuery, useQueryClient, queryOptions } from '@tanstack/react-query'
// ...

const options = queryOptions<ResponseValue>({
  queryKey: ['delay'],
  queryFn: async () => (await fetch('https://api.heropy.dev/v0/delay?t=1000')).json(),
  staleTime: 1000 * 10
})

export default function DelayedData() {
  const queryClient = useQueryClient()
  const { data, isStale } = useQuery(options)
  
  async function fetchData() {
    const data = await queryClient.fetchQuery(options)
    console.log(data) // Cached data or newly fetched data
  }
  return (
    <>
      <div>{data?.time}</div>
      <div>Is the data stale?: {JSON.stringify(isStale)}</div>
      <button onClick={fetchData}>Fetch data!</button>
    </>
  )
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import { useQuery, useQueryClient } from '@tanstack/react-query'
// ...

export default function DelayedData() {
  const queryClient = useQueryClient()
  const { data, isStale } = useQuery<ResponseValue>({
    queryKey: ['delay'],
    queryFn: async () => (await fetch('https://api.heropy.dev/v0/delay?t=1000')).json(),
    staleTime: 1000 * 10
  })
  
  function getCachedData() {
    const data = queryClient.getQueryData(['delay'])
    console.log(data) // Cached data or undefined
  }
  return (
    <>
      <div>{data?.time}</div>
      <div>Is the data stale?: {JSON.stringify(isStale)}</div>
      <button onClick={getCachedData}>Fetch data!</button>
    </>
  )
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
import { Fragment, useState } from 'react'
import { useInfiniteQuery } from '@tanstack/react-query'

export interface Page {
  Search: Movie[] // List of movies found
  totalResults: string // Total number of results found
  Response: string // 'True' or 'False'
}
export interface Movie {
  Title: string
  Year: string
  imdbID: string
  Type: string
  Poster: string
}

export default function MovieList() {
  const [searchText, setSearchText] = useState('')
  const [queryText, setQueryText] = useState('')

  const {
    data, // Fetched data
    isLoading, // Fetching the first page
    isFetching, // Fetching (including the first page)
    isFetched, // First page fetched
    hasNextPage, // Whether there is a next page
    fetchNextPage // Function that fetches the next page
  } = useInfiniteQuery<Page>({
    queryKey: ['movies', queryText], // Build the query key from the search term!
    queryFn: async ({ pageParam }) => {
      const res = await fetch(`https://omdbapi.com/?apikey=7035c60c&s=${queryText}&page=${pageParam}`)
      return res.json()
    },
    initialPageParam: 1, // Initialize the first page number!
    getNextPageParam: (lastPage, pages) => {
      // Each page fetches up to 10 movies!
      // Calculate the last page number!
      const maxPage = Math.ceil(Number(pages[0].totalResults) / 10)
      const currentPage = pages.length

      // If there is a next page, return the next page number!
      if (lastPage.Response === 'True' && currentPage < maxPage) {
        return currentPage + 1
      }
      // If there is no next page, return undefined | null!
      return null
    },
    enabled: Boolean(queryText), // Wait until a search term is entered!
    staleTime: 1000 * 60 * 60 // 1 hour
  })

  function handleSubmit(e: React.FormEvent) {
    e.preventDefault()
    // Search!
    setQueryText(searchText)
  }

  return (
    <>
      <form onSubmit={handleSubmit}>
        <input
          type="text"
          value={searchText}
          placeholder="Enter a movie title."
          onChange={e => setSearchText(e.target.value)}
        />
        <button type="submit">Search</button>
      </form>
      <div>
        {data?.pages.map((page, index) => (
          // Add a key per page to optimize rendering of each page!
          <Fragment key={index}>
            {page.Search &&
              page.Search.map(movie => (
                <div key={movie.imdbID}>{movie.Title}</div>
              ))}
          </Fragment>
        ))}
      </div>
      {isLoading ? <div>Loading..</div> : null}
      {isFetched && hasNextPage && (
        <button
          disabled={isFetching}
          onClick={() => fetchNextPage()}>
          {isFetching ? 'Loading..' : 'Load more!'}
        </button>
      )}
    </>
  )
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
import { Fragment, useState, useEffect, useRef } from 'react'
import { useInfiniteQuery } from '@tanstack/react-query'

// ...

export default function MovieList() {
  const [searchText, setSearchText] = useState('')
  const [queryText, setQueryText] = useState('')
  const observerEl = useRef<HTMLDivElement | null>(null)

  const {
    data,
    // isLoading,
    isFetching,
    // isFetched,
    hasNextPage,
    fetchNextPage
  } = useInfiniteQuery<Page>({
    // ...
  })

  useEffect(() => {
    const currentObserverEl = observerEl.current
    const io = new IntersectionObserver(entries => {
      if (entries[0].isIntersecting) {
        fetchNextPage()
      }
    }, {
      rootMargin: '0px 0px 500px 0px'
    })
    if (currentObserverEl) {
      io.observe(currentObserverEl)
    }
    return () => {
      if (currentObserverEl) {
        io.disconnect()
      }
    }
  }, [fetchNextPage])

  // ...

  return (
    <>
      {/* ... */}
      {/* {isLoading ? <div>Loading..</div> : null}
      {isFetched && hasNextPage && (
        <button
          disabled={isFetching}
          onClick={() => fetchNextPage()}>
          {isFetching ? 'Loading..' : 'Load more!'}
        </button>
      )} */}
      {isFetching && <div>Loading..</div>}
      <div
        ref={observerEl}
        style={{
          display: isFetching || !hasNextPage ? 'none' : 'block',
          height: '20px'
        }}
      />
    </>
  )
}

1
npm i react-intersection-observer

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
import { useState, useEffect } from 'react'
import { useInfiniteQuery } from '@tanstack/react-query'
import { useInView } from 'react-intersection-observer'

// ...

export default function MovieList() {
  const [searchText, setSearchText] = useState('')
  const [queryText, setQueryText] = useState('')
  const { ref, inView } = useInView({
    rootMargin: '0px 0px 500px 0px'
  })

  // ...

  // useEffect(() => {
  //   const currentObserverEl = observerEl.current
  //   const io = new IntersectionObserver(entries => {
  //     if (entries[0].isIntersecting && hasNextPage) {
  //       fetchNextPage()
  //     }
  //   })
  //   if (currentObserverEl) {
  //     io.observe(currentObserverEl)
  //   }
  //   return () => {
  //     if (currentObserverEl) {
  //       io.disconnect()
  //     }
  //   }
  // }, [hasNextPage, fetchNextPage])

  useEffect(() => {
    if (inView) {
      fetchNextPage()
    }
  }, [inView, fetchNextPage])

  // ...

  return (
    <>
      {/* ... */}
      {isFetching && <div>Loading..</div>}
      <div
        ref={ref}
        style={{
          display: isFetching || !hasNextPage ? 'none' : 'block',
          height: '20px'
        }}
      />
    </>
  )
}

1
2
3
4
5
6
7
import { infiniteQueryOptions } from '@tanstack/react-query'

infiniteQueryOptions({
  select: data => data.pages.flatMap(page => {
    return page.Response === 'True' ? page.Search : []
  })
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
import { useQuery } from '@tanstack/react-query'

export type Users = User[]
export interface User {
  name: string
  age: number
  isValid?: boolean
  emails?: string[]
  photo?: {
    name: string
    data: string // Base64
  }
  id?: string
}

export default function Users() {
  const { data } = useQuery<Users>({
    queryKey: ['users'],
    queryFn: async () => {
      const res = await fetch('https://api.heropy.dev/v0/users') // GET
      const json = await res.json()
      return json.users
    },
    staleTime: 1000 * 60 * 5 // 5 minutes
  })

  // ...
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
import React, { useState } from 'react'
import { useMutation, useQueryClient } from '@tanstack/react-query'
import type { Users, User } from './Users'

export default function AddUser() {
  const [name, setName] = useState('')
  const [age, setAge] = useState(0)
  const queryClient = useQueryClient()

  const { mutate, error, isPending, isError } = useMutation({
    mutationFn: async (newUser: User) => {
      const res = await fetch('https://api.heropy.dev/v0/users', {
        method: 'POST',
        body: JSON.stringify(newUser)
      })
      if (!res.ok) throw new Error('An error occurred during the mutation!') // Mutation failed!
      return res.json() // Mutation succeeded!
    },
    onMutate: async newUser => {
      // Cancel the user list query before the optimistic update to prevent potential conflicts!
      await queryClient.cancelQueries({ queryKey: ['users'] })

      // Get the cached data (user list)!
      const previousUsers = queryClient.getQueryData<Users>(['users'])

      // Optimistic update
      if (previousUsers) {
        queryClient.setQueryData<Users>(['users'], [...previousUsers, newUser])
      }

      // Return the data to pass to each callback as context!
      return { previousUsers }
    },
    onSuccess: (data, newUser, onMutateResult) => {
      console.log('onSuccess', data, newUser, onMutateResult)
      // On success, invalidate the cache to refresh the user list data!
      queryClient.invalidateQueries({ queryKey: ['users'] })
    },
    onError: (error, newUser, onMutateResult) => {
      console.log('onError', error, newUser, onMutateResult)
      // On failure, roll back the optimistic update to the previous user list!
      if (onMutateResult) {
        queryClient.setQueryData(['users'], onMutateResult.previousUsers)
      }
    },
    onSettled: (data, error, newUser, onMutateResult) => {
      console.log('onSettled', data, error, newUser, onMutateResult)
    },
    retry: 3, // Retry 3 times if the mutation fails
    retryDelay: 500 // Retry at 0.5-second intervals
  })

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault()
    mutate({ name, age }) // Mutate!
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={name}
        onChange={e => setName(e.target.value)}
        placeholder="User name"
      />
      <input
        type="number"
        value={age || ''}
        onChange={e => setAge(Number.parseInt(e.target.value, 10))}
        placeholder="User age"
      />
      <button
        type="submit"
        disabled={isPending}>
        {isPending ? 'Adding user..' : 'Add user!'}
      </button>
      {isError && <p>Error: {error.message}</p>}
    </form>
  )
}