v5.md

💻 Migrating to TanStack Query(React) v5

📄 주요 변동 사항 (⭐️ 중요)

1. ⭐️ Supports a single signature, one object

• useQuery, useInfiniteQuery, useMutation이 이제는 객체 형식만 지원하도록 변경되었습니다.
• v4에서는 useQuery(key, fn, options), useQuery({ queryKey, queryFn, ...options }) 두 형태를 모두 지원했는데 이는 유지보수가 힘들고, 매개 변수 타입을 확인하기 위한 런타임 검사도 필요했기 때문에 오로지 객체 형식만 지원하도록 v5에서 변경되었습니다.

- useQuery(key, fn, options)
+ useQuery({ queryKey, queryFn, ...options })
- useInfiniteQuery(key, fn, options)
+ useInfiniteQuery({ queryKey, queryFn, ...options })
- useMutation(fn, options)
+ useMutation({ mutationFn, ...options })
- useIsFetching(key, filters)
+ useIsFetching({ queryKey, ...filters })
- useIsMutating(key, filters)
+ useIsMutating({ mutationKey, ...filters })

- queryClient.isFetching(key, filters)
+ queryClient.isFetching({ queryKey, ...filters })
- queryClient.ensureQueryData(key, filters)
+ queryClient.ensureQueryData({ queryKey, ...filters })
- queryClient.getQueriesData(key, filters)
+ queryClient.getQueriesData({ queryKey, ...filters })
- queryClient.setQueriesData(key, updater, filters, options)
+ queryClient.setQueriesData({ queryKey, ...filters }, updater, options)
- queryClient.removeQueries(key, filters)
+ queryClient.removeQueries({ queryKey, ...filters })
- queryClient.resetQueries(key, filters, options)
+ queryClient.resetQueries({ queryKey, ...filters }, options)
- queryClient.cancelQueries(key, filters, options)
+ queryClient.cancelQueries({ queryKey, ...filters }, options)
- queryClient.invalidateQueries(key, filters, options)
+ queryClient.invalidateQueries({ queryKey, ...filters }, options)
- queryClient.refetchQueries(key, filters, options)
+ queryClient.refetchQueries({ queryKey, ...filters }, options)
- queryClient.fetchQuery(key, fn, options)
+ queryClient.fetchQuery({ queryKey, queryFn, ...options })
- queryClient.prefetchQuery(key, fn, options)
+ queryClient.prefetchQuery({ queryKey, queryFn, ...options })
- queryClient.fetchInfiniteQuery(key, fn, options)
+ queryClient.fetchInfiniteQuery({ queryKey, queryFn, ...options })
- queryClient.prefetchInfiniteQuery(key, fn, options)
+ queryClient.prefetchInfiniteQuery({ queryKey, queryFn, ...options })

- queryCache.find(key, filters)
+ queryCache.find({ queryKey, ...filters })
- queryCache.findAll(key, filters)
+ queryCache.findAll({ queryKey, ...filters })

2. ⭐️ 'queryClient.getQueryData', 'queryClient.getQueryState' now accepts queryKey only as an Argument

• queryClient.getQueryData의 인수가 queryKey만 받도록 v5에서 수정되었습니다.

- queryClient.getQueryData(queryKey, filters)
+ queryClient.getQueryData(queryKey)

• 마찬가지로 queryClient.getQueryState도 인수가 queryKey만 받도록 v5에서 수정되었습니다.

- queryClient.getQueryState(queryKey, filters)
+ queryClient.getQueryState(queryKey)

3. ⭐️ Callbacks on useQuery (and QueryObserver) have been removed

• useQuery의 옵션인 onSuccess, onError, onSettled가 제거되었습니다.
  • 해당 콜백 함수들은 간단하고, 직관적이라 굉장히 유용하지만 버그를 유발 할 수 있습니다.
• 자세한 내용은 Tanstack Query maintainer인 tkdodo 블로그 포스팅을 참고해주시기 바랍니다.

4. The 'remove' method has been removed from useQuery

• useQuery의 remove 메서드가 제거되었습니다. 이전에는 remove 메서드는 observer에게 알리지 않고 쿼리를 queryCache에서 제거하는데 사용했습니다.

  • 예를 들어, 사용자를 로그아웃 할 때와 같이 더 이상 필요하지 않은 데이터를 제거할 때와 같은 경우에 활용 할 수 있는 메서드였습니다.

• 하지만, query가 아직 활성화된 상태에서 이 remove 메서드를 호출하는 것은 다음 번 리렌더링 할 때 hard loading 상태를 트리거하기 때문에 합리적이지 못합니다.

  • 여기서, hard loading 상태란? 데이터가 없는 즉, 초기 데이터를 불러올 때 로딩 상태를 말합니다.
  • useQuery에서 자주 사용하는 isLoading이 이런 hard loading 상태인 경우에만 참(true)입니다.
  • When we refetch a query, it doesn't set isLoading true.

• 하지만!! 그럼에도 불구하고 쿼리를 제거해야 된다면 queryClient.removeQueries를 사용하면 됩니다.

const queryClient = useQueryClient();
const query = useQuery({ queryKey, queryFn });
- query.remove()
+ queryClient.removeQueries({ queryKey })

5. The 'isDataEqual' option has been removed from useQuery

• isDataEqual 함수는 query에서 resolved된 데이터로서 이전 데이터를 사용할지 아니면 새 데이터를 사용할지 확인하는데 사용했습니다.
• 이제는 isDataEqual을 사용하지 않고, 동일한 기능으로서 structuralSharing으로 활용할 수 있습니다.

import { replaceEqualDeep } from '@tanstack/react-query'

- isDataEqual: (oldData, newData) => customCheck(oldData, newData)
+ structuralSharing: (oldData, newData) => customCheck(oldData, newData) ? oldData : replaceEqualDeep(oldData, newData)

6. ⭐️ Rename 'cacheTime' to 'gcTime'

• cacheTime이 gcTime으로 변경되었습니다.
  • 네이밍이 변경된 이유는 많은 사람들이 cacheTime을 마치 "데이터가 캐시되는 시간"으로 착각하기 때문입니다.
  • 하지만, 실제로 query가 계속 사용되는 한cacheTime은 아무 일도 하지 않고, query가 더이상 사용되지 않는 시점에 시작됩니다. 그리고 cacheTime 시간이 지나면 캐시가 더이상 커지는 것을 방지하기 위해 데이터는 garbage collected됩니다.
• 따라서, 의미상의 혼동을 줄이기 위해 cacheTime에서 gcTime으로 변경되었습니다.

const MINUTE = 1000 * 60;

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
-      cacheTime: 10 * MINUTE,
+      gcTime: 10 * MINUTE,
    },
  },
})

7. ⭐️ The 'useErrorBoundary' option has been renamed to 'throwOnError'

• 기존에 ErrorBoundary에 에러를 던지기 위해 사용했던 옵션인 useErrorBoundary를 특정 프레임워크에 종속되지 않으면서, 리액트 커스텀 훅의 접미사인 use와 ErrorBoundary 컴포넌트명과 혼동을 피하기 위해, throwOnError로 변경됐습니다.

const todos = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
-  useErrorBoundary: true,
+  throwOnError: true,
})

8. ⭐️ TypeScript: 'Error' is now the default type for errors instead of 'unknown'

• v5 부터는 error의 기본 타입이 Error 입니다. 변경된 이유는 많은 사용자들이 기대하는 결과이기 때문입니다.

// const error: Error
const { error } = useQuery({
  queryKey: ["groups"],
  queryFn: fetchGroups,
});

• 만약 커스텀 에러를 활용하거나 Error가 아닌 것을 활용하고 싶다면, 아래 예제처럼 타입을 구체화할 수 있습니다.

// const error: string | null
const { error } = useQuery<Group[], string>({
  queryKey: ["groups"],
  queryFn: fetchGroups,
});

9. ⭐️ Removed 'keepPreviousData' in favor of 'placeholderData' identity function

• ​keepPreviousData 옵션과 isPreviousData 플래그가 제거되었습니다.
  • 왜냐하면 이들은 각각 placeholderData와 `isPlaceholderData 플래그와 거의 유사하게 동작하기 때문입니다.
• 아래 예제는 placeholderData를 활용하면서 이전에 keepPreviousData 옵션을 true로 줬을때와 동일한 기능을 수행하기 위해 identity function을 허용하는 placeholderData에 Tanstack Query에 포함된 keepPreviousData 함수를 추가하였습니다.

import {
   useQuery,
+  keepPreviousData
} from "@tanstack/react-query";

const {
   data,
-  isPreviousData,
+  isPlaceholderData,
} = useQuery({
  queryKey,
  queryFn,
- keepPreviousData: true,
+ placeholderData: keepPreviousData
});

• 또는, 직접 identity function을 제공하는 방법도 있습니다.

useQuery({
  queryKey,
  queryFn,
  placeholderData: (previousData, previousQuery) => previousData,
  // identity function with the same behaviour as `keepPreviousData`
});

• 여기서 위 변경사항에는 몇 가지 주의사항이 있습니다.

  • placeholderData는 항상 success 상태를 유지하며, keepPreviousData는 이전 쿼리 상태를 알려줍니다. 데이터를 성공적으로 가져온 후 background refetch error가 발생하면 placeholderData의 success 상태는 오류라고 느낄 수 있습니다. 하지만 에러 자체가 공유되지 않기 때문에 placeholderData의 동작은 그대로 유지하기로 결정됐습니다.

  • keepPreviousData를 사용할 때는 이전 데이터의 dateUpdatedAt 타임 스탬프가 제공되었는데, placeholderData를 사용하면 dateUpdatedAt은 0으로 유지됩니다.

  • 만약, 타임스탬프를 화면에 계속 보여주고 싶다면 이런 동작이 불만족스러울 수 있습니다. 이러한 문제는 아래와 같이 useEffect를 활용하면 해결할 수 있습니다.

const [updatedAt, setUpdatedAt] = useState(0);

const { data, dataUpdatedAt } = useQuery({
  queryKey: ["projects", page],
  queryFn: () => fetchProjects(page),
});

useEffect(() => {
  if (dataUpdatedAt > updatedAt) {
    setUpdatedAt(dataUpdatedAt);
  }
}, [dataUpdatedAt]);

10. ⭐️ Window focus refetching no longer listens to the 'focus' event

• Tanstack Query는 visibilitychange 이벤트를 지원하는 브라우저만 지원하도록 결정됐습니다. 따라서, 이제 visibilitychange 이벤트만 독점적으로 사용됩니다.
• 이를 통해 다음 focus 관련 문제가 해결되었습니다.

11. Removed custom 'context' prop in favor of custom 'queryClient' instance

• 커스텀 queryClient 인스턴스를 위해 커스텀 context prop이 제거되었습니다.
• 기존 v4에서는 context를 모든 react query hooks에 전달할 수 있는 방법을 제공했습니다. 이는 MicroFrontends를 사용할 때 적절하게 격리할 수 있게 했습니다.
• 하지만, 다들 알다싶이 context는 리액트에서만 사용 가능한 기능입니다. context는 que`ryClient에 대한 접근 권한을 주는 역할을 할 뿐입니다.
• v5에서는 위와 동일한 기능을 아래 예제처럼 커스텀 queyClient를 직접 전달함으로써 해결했습니다. 이제는 어떤 다른 프레임워크에 구애받지 않고 동일한 기능을 사용할 수 있습니다.

import { queryClient } from './my-client'

const { data } = useQuery(
  {
    queryKey: ['users', id],
    queryFn: () => fetch(...),
-   context: customContext
  },
+  queryClient,
)

12. ⭐️ Removed 'refetchPage' in favor of 'maxPages'

• maxPages를 위해 refetchpage를 제거하였습니다.
• v4에서는 refetchPage 함수를 사용하여 infinite queries에 대해 refresh 할 페이지를 정의할 수 있는 기능을 제공했습니다.
• 그러나 모든 페이지를 refresh 하면 UI 불일치가 발생할 수 있습니다. 또한 이 옵션은 queryClient.refetchQueries에서 사용할 수 있지만 nomal queries가 아닌 infinite queries에대해서만 동작합니다.
• v5에서는 query data를 저장하고, 다시 가져올 수 있는 페이지 수를 제한하는 infinite queries를 위한 새로운 maxPages 옵션이 포함되어 있습니다.

useInfiniteQuery({
  queryKey: ["projects"],
  queryFn: fetchProjects,
  initialPageParam: 0,
  getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
  getPreviousPageParam: (firstPage, pages) => firstPage.prevCursor,
  maxPages: 3,
});

• infinite queries는 많은 페이지를 가져올수록 더 많은 메모리를 사용하게 되며, 모든 페이지를 순차적으로 다시 가져오기 때문에 query refetching 프로세스도 느려집니다.
• maxPages를 활용하면 페이지 수를 제한하고 이후에 다시 가져올 수 있기 때문에 이런 단점을 보완할 수 있습니다. 참고로 infinite list는 양방향이여야 하기 때문에 위 예제처럼 getNextPageParam과 getPreviousPageParam을 모두 정의해야 한다는 점을 주의해야 합니다.

13. ⭐️ infinite queries now need a 'initialPageParam'

• 이전에는 undefined 값을 가진 pageParam을 queryFn에 전달했고, queryFn에서 pageParam에 대한 기본 값을 정의했습니다. 하지만 이런 경우 직렬화 할 수 없는 쿼리 캐시에 undefined인 상태로 저장된다는 단점이 있습니다.
• v5부터는 아래 예제처럼 infinite Query 옵션에 명시적인 initialPageParam을 전달해야 합니다.

useInfiniteQuery({
   queryKey,
-  queryFn: ({ pageParam = 0 }) => fetchSomething(pageParam),
+  queryFn: ({ pageParam }) => fetchSomething(pageParam),
+  initialPageParam: 0,
   getNextPageParam: (lastPage) => lastPage.next,
})

14. Manual mode for infinite queries has been removed

• 이전에는 아래 예제처럼 pageParams 값을 수동적으로 fetchNextPage 또는 fetchPreviousPage에 직접 전달하여 getNextPageParam 또는 getPreviousPageParam에서 반환되는 pageParam를 덮어쓰는 것이 허용되었습니다.

// v4
function Projects() {
  const fetchProjects = ({ pageParam = 0 }) =>
    fetch("/api/projects?cursor=" + pageParam);

  const {
    status,
    data,
    isFetching,
    isFetchingNextPage,
    fetchNextPage,
    hasNextPage,
  } = useInfiniteQuery({
    queryKey: ["projects"],
    queryFn: fetchProjects,
    getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
  });

  // Pass your own page param
  const skipToCursor50 = () => fetchNextPage({ pageParam: 50 });
}

• 하지만 이 pageParam을 덮어쓰는 기능은 refetch에서는 전혀 작동하지 않았고, 많은 사람들이 사용하는 기능이 아니였습니다. 즉, infinite queries에서 getNextPageParam이 필수적임을 의미합니다.

15. ⭐️ Returning 'null' from 'getNextPageParam' or 'getPreviousPageParam' now indicates that there is no further page available

• v4에서는 더 이상 페이지 없음을 나타내기 위해 명시적으로 undefined를 반환해야 했습니다. v5부터는 undefined 뿐만 아니라 null까지 포함하도록 확장됐습니다.

getNextPageParam: (lastPage, allPages, lastPageParam, allPageParams) =>
  TPageParam | undefined | null;

getPreviousPageParam: (firstPage, allPages, firstPageParam, allPageParams) =>
  TPageParam | undefined | null;

16. No retries on the server

• 서버에서 retry의 기본 값은 3이 아닌 0입니다.
• prefetching의 경우 항상 기본값이 0이였지만, suspense가 활성화된 쿼리는 이제 서버에서도 직접 실행할 수 있기 때문에(React v18 이후) 서버에서 재시도를 전혀 하지 않도록 해야합니다.

17. ⭐️ 'status: loading' has been changed to 'status: pending' and 'isLoading' has been changed to 'isPending' and 'isInitialLoading' has now been renamed to 'isLoading'

• loading 옵션이 pending으로 변경되었으며, 마찬가지로 isLoading 플래그가 isPending으로 변경되었습니다.

isPending: boolean;
// A derived boolean from the status variable above, provided for convenience.
isSuccess: boolean;
// A derived boolean from the status variable above, provided for convenience.
isError: boolean;
// A derived boolean from the status variable above, provided for convenience.

• mutation의 경우에도 isLoading 플래그가 isPending으로 변경되었습니다.

status: string;
/*
  Will be:
    - 'idle' initial status prior to the mutation function executing.
    - 'pending' if the mutation is currently executing.
    - 'error' if the last mutation attempt resulted in an error.
    - 'success' if the last mutation attempt was successful.
  'isIdle', 'isPending', 'isSuccess', 'isError': boolean variables derived from 'status'
 */

• 그리고 isPending && isFetching으로 구현되는 새로운 isLoading 플래그가 추가되었습니다.
• 이는 기존의 isInitialLoading과 동일한 기능을 하는데, isInitialLoading은 더 이상 사용되지 않으며 다음 메이저 버전 업데이트에서 제거될 예정입니다.

18. Simplified optimistic updates

• v5부터는 낙관적 업데이트를 수행하는 단순한 방법을 제공합니다.

const queryInfo = useTodos();
const addTodoMutation = useMutation({
  mutationFn: (newTodo: string) => axios.post("/api/data", { text: newTodo }),
  onSettled: () => queryClient.invalidateQueries({ queryKey: ["todos"] }),
});

if (queryInfo.data) {
  return (
    <ul>
      {queryInfo.data.items.map((todo) => (
        <li key={todo.id}>{todo.text}</li>
      ))}
      {addTodoMutation.isPending && (
        <li key={String(addTodoMutation.submittedAt)} style={{ opacity: 0.5 }}>
          {addTodoMutation.variables}
        </li>
      )}
    </ul>
  );
}

• 위 예제에서는 데이터를 캐시에 직접 쓰는 대신에 mutation이 실행중일 때 UI가 표시되는 방식만 변경합니다. 해당 방법은 낙관적 업데이트를 표시해야 하는 위치가 한 곳만 있는 경우에 효과적입니다.
• 낙관적 업데이트와 관련된 자세한 내용은 optimistic-updates를 참고해주시길 바랍니다.

19. Infinite Queries can prefetch multiple Pages

• 이제 infinite queries도 normal queries처럼 prefetch 할 수 있습니다.
• 기본적으로 query의 첫 번째 페이지만 prefetch되며 지정된 queryKey 아래에 저장됩니다. 두 개 이상의 페이지를 미리 가져오려면 pages 옵션을 사용하면 됩니다.
• prefetch와 관련된 자세한 내용은 prefetching를 참고해주시길 바랍니다.

const prefetchTodos = async () => {
  // The results of this query will be cached like a normal query
  await queryClient.prefetchInfiniteQuery({
    queryKey: ["projects"],
    queryFn: fetchProjects,
    initialPageParam: 0,
    getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
    pages: 3, // prefetch the first 3 pages
  });
};

20. new 'combine' option for 'useQueries'

• useQueries 결과 데이터를 단일 값으로 결합하려면 combine 옵션을 사용할 수 있습니다.

const ids = [1,2,3]
const combinedQueries = useQueries({
  queries: ids.map(id => (
    { queryKey: ['post', id], queryFn: () => fetchPost(id) },
  )),
  combine: (results) => {
    return ({
      data: results.map(result => result.data),
      pending: results.some(result => result.isPending),
    })
  }
})

• 위 예제에서는 combinedQueries는 data와 pending 속성이 있는 객체가 됩니다. 쿼리 결과의 다른 모든 속성은 손실된다는 점을 주의해야 됩니다.

​21. ⭐️ new hooks for suspense

• v5에서는 data fetching에 대한 suspense가 마침내 안정화되었습니다.
• useSuspenseQuery, useSuspenseInfiniteQuery, useSuspenseQueries 3가지 훅이 추가되었습니다.
• 위 3가지 훅을 사용하게 되면 타입 레벨에서 data가 undefined 상태가 되지 않습니다.

import { useSuspenseQuery } from "@tanstack/react-query";

const { data } = useSuspenseQuery({ queryKey, queryFn });

• suspense와 관련된 자세한 내용은 suspense를 참고해주시길 바랍니다.

22. ⭐️ The minimum required TypeScript version is now 4.7

• Tanstack Query v5는 필요한 TypeScript 최소 버전이 v4.7입니다.

23. ⭐️ The minimum required React version is now 18.0

• Tanstack Query v5는 필요한 React 최소 버전이 v18.0입니다. 이는 React v18 이상에서만 사용할 수 있는 useSyncExternalStore 훅을 사용하고 있기 때문입니다.

24. ⭐️ Supported Browsers

Chrome >= 91
Firefox >= 90
Edge >= 91
Safari >= 15
iOS >= 15
opera >= 77