TanStack Query(구 React Query)는 이제 프론트엔드 데이터 페칭의 표준이라고 해도 과언이 아니죠.

서버 상태를 아주 우아하게 관리해주지만, 혹시 이 도구의 잠재력을 100% 끌어내고 계신가요?

오늘은 TanStack Query를 그냥 ‘잘 쓰는’ 수준을 넘어, ‘마스터하는’ 두 가지 고급 패턴에 대해 이야기해 보려고 하는데요.

첫 번째는 타입스크립트를 활용해 우리의 API 훅을 총알도 막아낼 만큼 견고하게 만드는 방법이고요.

두 번째는 ‘프리페칭’을 통해 사용자가 로딩 스피너를 볼 틈도 없이 데이터를 보여주는 마법 같은 사용자 경험을 만드는 기술입니다.

이 두 가지만 제대로 익혀도 여러분의 애플리케이션은 코드 품질과 사용자 경험 양쪽에서 한 단계 도약할 수 있을 거예요.

타입스크립트로 TanStack Query 날개 달아주기

TanStack Query를 타입스크립트와 함께 쓰면 자동 완성, 컴파일 타임 에러 체크 등 정말 많은 이점을 누릴 수 있는데요.

이걸 제대로 활용하면 아주 견고하고 재사용성 높은 데이터 훅을 만들 수 있습니다.

기본부터 탄탄하게, 제네릭으로 타입 지정하기

가장 기본적인 useQuery 사용법부터 타입스크립트를 적용해 보죠.

import { useQuery } from '@tanstack/react-query';

type User = {
  id: string;
  name: string;
};

const fetchUser = async (): Promise<User> => {
  const res = await fetch('/api/user');
  if (!res.ok) throw new Error('Failed to fetch');
  return res.json();
};

export function useUserQuery() {
  return useQuery<User>(['user'], fetchUser);
}

여기서 핵심은 useQuery<User> 부분인데요.

이렇게 제네릭으로 User 타입을 명시해주면, TanStack Query는 이 쿼리가 성공했을 때 반환될 data의 타입이 User라는 것을 알게 됩니다.

덕분에 data.name 같은 속성에 접근할 때 자동 완성이 지원되고, 만약 오타라도 나면 컴파일러가 바로 에러를 뱉어주죠.

옵션을 타입으로 정의해서 재사용하기

쿼리 옵션을 별도의 타입으로 추출해서 재사용성을 높일 수도 있는데요.

UseQueryOptions 타입을 활용하면 됩니다.

import { UseQueryOptions } from '@tanstack/react-query';

type UserQueryOptions = UseQueryOptions<
  User,         // TQueryFnData: queryFn이 반환하는 데이터 타입
  Error,        // TError: 에러 발생 시 에러 객체의 타입
  User,         // TData: 최종적으로 컴포넌트에 전달될 데이터 타입
  ['user']      // TQueryKey: 쿼리 키의 타입
>;

export const useUserQuery = (options?: UserQueryOptions) => {
  return useQuery(['user'], fetchUser, options);
};

이렇게 UserQueryOptions라는 타입을 만들어두면, 이 쿼리에 특화된 옵션들을 타입 안전하게 관리하고 다른 곳에서도 쉽게 재사용할 수 있게 되죠.

제네릭 훅으로 궁극의 재사용성 달성하기

여기서부터가 진짜 재미있는 부분인데요.

아예 어떤 데이터 타입이든 처리할 수 있는 범용적인 useTypedQuery 훅을 만들어서 반복 작업을 극적으로 줄일 수 있습니다.

마치 우리만의 미니 API 팩토리를 만드는 것과 같죠.

import { useQuery, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';

export function useTypedQuery<
  TData, 
  TError = Error, 
  TQueryKey extends readonly unknown[] = any
>(
  key: TQueryKey,
  queryFn: () => Promise<TData>,
  options?: UseQueryOptions<TData, TError, TData, TQueryKey>
): UseQueryResult<TData, TError> {
  return useQuery(key, queryFn, options);
}

이 useTypedQuery는 데이터 타입(TData), 에러 타입(TError), 쿼리 키 타입(TQueryKey)을 제네릭으로 받아서 useQuery를 한번 감싼 래퍼 훅인데요.

이걸 사용하면 새로운 쿼리 훅을 만드는 게 정말 간단해집니다.

type Product = { id: number; name: string };

function useProductQuery(id: number) {
  return useTypedQuery<Product>(
    ['product', id], 
    () => fetch(`/api/products/${id}`).then(res => res.json())
  );
}

보세요.

이제 useProductQuery를 만들 때 useTypedQuery를 호출하면서 데이터 타입과 쿼리 키, 그리고 queryFn만 넘겨주면 됩니다.

복잡한 타입 정의는 useTypedQuery 안에 모두 캡슐화되어 있죠.

이런 패턴은 특히 여러 엔티티를 다루는 큰 프로젝트에서 빛을 발합니다.

잠깐, 타입스크립트의 추론 능력을 믿어보세요

한 가지 더 팁을 드리자면, queryFn을 인라인 함수로 작성하고 반환 타입을 Promise<T>로 명시해주면 타입스크립트가 알아서 데이터 타입을 추론해주거든요.

useQuery(['user'], async (): Promise<User> => {
  return fetch('/api/user').then(res => res.json());
});

덕분에 굳이 useQuery<User>처럼 제네릭을 명시하지 않아도 타입 안전성을 누릴 수 있는 거죠.

로딩 스피너를 추방하는 프리페칭의 마법

이제 우리 쿼리가 타입스크립트로 안전해졌으니, 다음은 사용자 경험을 극적으로 끌어올릴 차례인데요.

‘프리페칭(Prefetching)‘은 사용자가 그 데이터를 요청하기도 ‘전에’ 미리 가져와서 캐시에 살짝 숨겨두는 기술입니다.

사용자가 링크를 클릭하는 순간, 데이터는 이미 준비되어 있기 때문에 로딩 스피너 없이 즉시 화면이 나타나는 마법 같은 경험을 선사할 수 있죠.

가장 기본적인 프리페칭 마우스 호버

프리페칭을 트리거하는 가장 흔하고 효과적인 방법은 사용자가 링크에 마우스를 올렸을 때인데요.

사용자가 링크에 마우스를 올렸다는 건, 그 페이지로 이동할 ‘의도’가 있다는 강력한 신호거든요.

import { useQueryClient } from '@tanstack/react-query';

const fetchPost = async (id: number) => {
  // ... 게시글 데이터를 가져오는 로직
};

export default function PostLink({ id }: { id: number }) {
  const queryClient = useQueryClient();

  return (
    <a
      href={`/posts/${id}`}
      onMouseEnter={() => {
        queryClient.prefetchQuery(['post', id], () => fetchPost(id));
      }}
    >
      게시글 #{id} 보기
    </a>
  );
}

useQueryClient 훅으로 쿼리 클라이언트 인스턴스를 가져온 뒤, <a> 태그의 onMouseEnter 이벤트 핸들러 안에서 queryClient.prefetchQuery를 호출하면 끝입니다.

이제 사용자가 이 링크에 마우스를 올리는 순간, 백그라운드에서 fetchPost가 실행되고 그 결과가 ['post', id]라는 키로 캐시되죠.

프리페칭 에러 처리, 잊지 마세요

그런데 이 prefetchQuery는 기본적으로 ‘실행하고 잊어버리는(fire-and-forget)’ 방식으로 동작하거든요.

그래서 만약 프리페칭 중에 네트워크 에러가 발생해도 조용히 무시해버립니다.

만약 에러를 로깅하거나 다른 처리를 하고 싶다면, 반드시 await 키워드를 사용해서 비동기적으로 처리해야 합니다.

try {
  await queryClient.prefetchQuery(['post', id], () => fetchPost(id));
} catch (err) {
  console.error('프리페칭 실패:', err);
}

이렇게 try-catch 블록으로 감싸주면 프리페칭 실패에 대한 예외 처리가 가능해집니다.

useQuery와의 아름다운 협업

이게 바로 프리페칭의 하이라이트죠.

사용자가 마침내 링크를 클릭해서 해당 게시글 페이지로 이동했다고 해봅시다.

그 페이지의 컴포넌트는 아마 이렇게 useQuery를 사용하고 있을 텐데요.

const { data } = useQuery(['post', id], () => fetchPost(id));

TanStack Query는 fetchPost를 실행하기 전에, 먼저 캐시에 ['post', id] 키에 해당하는 데이터가 있는지 확인합니다.

그런데 우리가 이미 프리페칭을 해뒀기 때문에, 캐시에는 신선한 데이터가 딱 준비되어 있죠.

그러면 TanStack Query는 네트워크 요청을 보내는 대신, 캐시에서 데이터를 즉시 꺼내 반환합니다.

결과는? 로딩 스피너 없는 즉각적인 화면 전환이죠.

사용자 입장에서는 정말 놀랍도록 빠른 속도를 체감하게 되는 겁니다.

또 다른 전략들 페이지 로드 시 프리페칭, 그리고 ensureQueryData

마우스를 올릴 때뿐만 아니라, 페이지가 처음 로드될 때 useEffect를 사용해서 데이터를 미리 가져와 캐시를 채워두는 전략도 유용한데요.

대시보드나 설정 페이지처럼 사용자가 높은 확률로 접근할 데이터를 미리 준비해두는 거죠.

useEffect(() => {
  queryClient.prefetchQuery(['settings'], fetchSettings);
}, [queryClient]);

또한 TanStack Query v5부터는 ensureQueryData라는 아주 편리한 API도 추가되었는데요.

이 함수는 캐시에 데이터가 있으면 즉시 반환하고, 없으면 queryFn을 실행해서 데이터를 가져온 뒤 그 결과를 반환하고 캐싱까지 해줍니다.

사용자 인증 정보처럼, 레이아웃 단에서 반드시 필요한 데이터를 미리 로드하거나 보장하는 데 아주 유용하죠.

마치며

오늘 우리는 TanStack Query를 한 단계 더 깊이 있게 사용하는 두 가지 강력한 패턴을 살펴봤는데요.

타입스크립트를 활용한 ‘제네릭 쿼리 훅’은 코드의 안정성과 재사용성을 극대화해서 우리의 개발 경험을 향상시켜주고요.

prefetchQuery와 ensureQueryData를 활용한 ‘스마트 프리페칭’은 로딩 시간을 최소화해서 사용자의 경험을 극적으로 끌어올려 줍니다.

이 두 가지 패턴을 잘 조합해서 사용한다면, 여러분은 분명 더 견고하고, 더 빠르고, 더 즐거운 웹 애플리케이션을 만들 수 있을 거예요.