TanStack Query의 모든 것

1. 소개

2. TanStack Query란?

2.1. 클라이언트 상태 vs 서버 상태

• 클라이언트 상태는 브라우저 안에서만 존재하는 상태로, 사용자의 입력값이나 UI 컴포넌트 간의 토글 상태 같은 것들을 의미합니다. 예를 들어 다크 모드 여부나 모달창의 열림/닫힘 상태 등이 여기에 해당하죠.

• 서버 상태는 서버와 네트워크를 통해 주고받는 데이터로, API 요청 결과나 DB에 저장된 정보를 불러오는 과정에서 관리하게 됩니다. 서버와 동기화되어야 하고, 캐싱·리페치(refetch)·에러 처리 등이 따라오기 때문에 단순히 useState로는 관리하기가 어렵습니다.

2.2. React Query → TanStack Query로의 확장

3. 핵심 개념

3.1. Query

// 기본적인 예시입니다. 
const { data, isLoading, error } = useQuery({
  queryKey: ['todos'],          // 캐싱을 위한 key
  queryFn: () => getTodos(),  // 실제 데이터를 불러오는 함수
});

3.2. Mutation

const mutation = useMutation({
  mutationFn: (newTodo) => createTodo(newTodo),
  onSuccess: () => {
    queryClient.invalidateQueries(['todos']); // 관련 쿼리 새로고침
  },
});

// 사용 예시
mutation.mutate({ title: '새 할 일' });

3.3. QueryClient

3.4. Devtools

• 현재 캐시된 데이터

• 각 Query의 상태 (loading, error, success)

• 자동 리페치가 일어나는 타이밍

4. 기본 사용법

4.1. useQuery

• 공통 규칙: 모든 컴포넌트에서 동일하게 적용되어야 할 queryKey, queryFn 등은 훅 내부에 정의합니다.

• 예외 허용: 특정 컴포넌트에서만 필요한 옵션(e.g., staleTime, enabled)은 options 파라미터로 받아와 적용할 수 있게 열어둡니다.

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

// Post 타입 정의
type Post = { id: number; title: string; };
type UsePostsQueryOptions = Omit<UseQueryOptions<Post[]>, 'queryKey' | 'queryFn'>;


// 커스텀 훅이 options를 인자로 받도록 설계
export const usePostsQuery = (options?: UsePostsQueryOptions) => {
  return useQuery({
    // 필수 옵션
    queryKey: ['posts'],
    queryFn: fetchPosts,
	  
	  // 추가 옵션
    ...options,
  });
};


// --- 컴포넌트에서의 사용 ---

// 일반적인 사용 (기본 staleTime 5분이 적용됨)
const { data } = usePostsQuery();


// 특정 페이지에서 staleTime을 10분으로 늘리고 싶을 때 (staleTime은 기본적으로 5분)
const { data: specialPosts } = usePostsQuery({
  staleTime: 1000 * 60 * 10,
});

// 특정 조건이 만족될 때만 쿼리를 실행하고 싶을 때
const { data: conditionalPosts } = usePostsQuery({
  enabled: someCondition === true,
});

4.2. useSuspense

• 데이터를 가져오는 중일 때는 컴포넌트 렌더링을 일시 중단(Suspend)시키고,

• 에러가 발생하면 에러를 던져서(Throw) 가장 가까운 Error Boundary에서 처리하도록 합니다.

언제 사용하나요?

• if (isPending) return <Spinner /> 와 같은 로딩 상태 분기문을 컴포넌트에서 제거하고 싶을 때

• 여러 데이터 요청의 로딩 상태를 <Suspense>를 통해 한 번에 관리하고 싶을 때

• 에러 처리를 <ErrorBoundary>를 통해 중앙에서 통합 관리하고 싶을 때

import { useSuspenseQuery, UseSuspenseQueryOptions } from '@tanstack/react-query';

type UseSuspensePostsQueryOptions = Omit<UseSuspenseQueryOptions<Post[]>, 'queryKey' | 'queryFn'>;

export const useSuspensePostsQuery = (options?: UseSuspensePostsQueryOptions) => {
  return useSuspenseQuery({
    // 공통 규칙: 고유 키와 데이터 fetcher
    queryKey: ['posts'],
    queryFn: fetchPosts,
    
    // 2. 예외 허용: 컴포넌트에서 받은 options 객체
    ...options,
  });
};

1. 데이터를 사용하는 컴포넌트

import { useSuspensePostsQuery } from './hooks/useSuspensePostsQuery';

function PostList() {
  // isPending, isError 없이 바로 data를 구조분해 할당.
  // 데이터 로딩이 끝나지 않았으면 이 컴포넌트는 여기서 잠시 중단된다.
  const { data: posts } = useSuspensePostsQuery();

  return (
    <ul>
      {posts.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

2. 컴포넌트를 감싸는 상위 컴포넌트
실제 로딩 및 에러 처리는 이 컴포넌트가 담당합니다. PostList가 중단되면 Suspense의 fallback UI가 대신 보여집니다. 에러가 발생하면 ErrorBoundary의 fallback UI가 보여집니다.

import { Suspense } from 'react';
import { ErrorBoundary } from 'react-error-boundary';
import PostList from './components/PostList';
import Spinner from './components/Spinner';
import ErrorMessage from './components/ErrorMessage';

function PostPage() {
  return (
    <div>
      <h1>게시글 목록</h1>
      <ErrorBoundary fallback={<ErrorMessage />}>
        <Suspense fallback={<Spinner />}>
          <PostList />
        </Suspense>
      </ErrorBoundary>
    </div>
  );
}

 
❗
그래서.. useQuery랑 useSuspenseQuery중 뭘 쓰나요?? 보통 전통적인 방식이면서 높은 자유도를 가진 useQuery를 사용합니다. isPending이나 isError 상태를 직접 다루는 것이 직관적이고, 컴포넌트 단위로 세밀한 UI 제어가 가능한 장점이 있습니다.
하지만, Plaid에서 B2B Saas로 저희가 기획부터 디자인까지 담당해서 제공하는 프로젝트라면… useSuspenseQuery를 사용하는 것도 좋을 것 같습니다. React가 지향하는 선언적인 UI 작성 방식과 맞아 떨어지기도하고, 코드 가독성과 유지 보수성도 크게 향상되는 장점이 있는 것 같습니다.
결론적으로… 일단 상세한 UI와 자유도가 높은 비지니스 로직이라면 useQuery를, 그 반대라면 useSuspenseQuery를 사용하는 것이 좋아보입니다.

4.3. useInfiniteQuery

• 인스타그램 피드나 페이스북 타임라인처럼 사용자가 아래로 스크롤할 때마다 새로운 콘텐츠를 계속 로드해야 할 때

• "더 보기" 버튼을 눌러 다음 페이지의 게시물 목록을 이어 붙여 보여주고 싶을 때

• 채팅 앱에서 이전 대화 내용을 위로 스크롤하여 불러올 때

• initialPageParam: 가장 처음에 요청할 페이지 번호(또는 커서)를 지정합니다.

• getNextPageParam: 마지막으로 성공한 API 응답 데이터를 기반으로, 다음에 요청할 페이지 번호가 무엇인지 계산하여 반환하는 함수입니다. 만약 더 이상 불러올 페이지가 없다면 undefined나 null을 반환합니다.

import { useInfiniteQuery, UseInfiniteQueryOptions } from '@tanstack/react-query';

type Post = { id: number; title: string; };
type PaginatedPosts = { data: Post[]; nextPage?: number; };

type UseInfinitePostsQueryOptions = Omit<
  UseInfiniteQueryOptions<PaginatedPosts>, 
  'queryKey' | 'queryFn' | 'initialPageParam' | 'getNextPageParam'
>;

// --- 커스텀 훅 ---
export const useInfinitePostsQuery = (options?: UseInfinitePostsQueryOptions) => {
  return useInfiniteQuery({
    queryKey: ['posts', 'infinite'],
    queryFn: fetchPosts,
    
    // infinite query에서 추가되는 핵심적인 옵션
    initialPageParam: 1, // 첫 페이지는 1번부터 시작
    getNextPageParam: (lastPage) => {
      // lastPage: 가장 최근에 받아온 페이지 데이터
      // lastPage.nextPage가 있으면 그 값을, 없으면 더 이상 페이지가 없다는 의미로 undefined 반환
      return lastPage.nextPage; 
    },
    ...options,
  });
};

• data.pages: 지금까지 불러온 모든 페이지의 데이터가 배열 형태로 담겨 있습니다. ([ [page1_data], [page2_data], ... ])

• fetchNextPage: 다음 페이지의 데이터를 요청하는 함수입니다.

• hasNextPage: getNextPageParam이 undefined를 반환하지 않으면 true가 됩니다. 더 불러올 페이지가 남았는지 알려줍니다.

• isFetchingNextPage: 다음 페이지 데이터를 불러오는 중일 때 true가 되는 로딩 상태입니다.

import { useInfinitePostsQuery } from './hooks/useInfinitePostsQuery';
import { Fragment } from 'react';

function InfinitePostList() {
  const {
    data,
    fetchNextPage,
    hasNextPage,
    isFetchingNextPage,
    isPending,
    isError,
  } = useInfinitePostsQuery();

  if (isPending) return <div>초기 데이터 로딩 중...</div>;
  if (isError) return <div>에러가 발생했습니다.</div>;

  return (
    <div>
      {data.pages.map((page, i) => (
        <Fragment key={i}>
          {page.data.map((post) => (
            <div key={post.id} className="post">
              {post.title}
            </div>
          ))}
        </Fragment>
      ))}

      <button
        onClick={() => fetchNextPage()}
        disabled={!hasNextPage || isFetchingNextPage}
      >
        {isFetchingNextPage
          ? '불러오는 중...'
          : hasNextPage
          ? '더 보기'
          : '마지막 페이지입니다'}
      </button>
    </div>
  );
}

4.4. useMutation

• mutationFn: 필수 항목. 서버에 변경 요청을 보내는 비동기 함수입니다. mutate 함수가 호출될 때 전달받은 변수를 인자로 받습니다.

• onSuccess: 뮤테이션이 성공했을 때 실행되는 콜백입니다. 가장 중요한 역할은 queryClient.invalidateQueries를 호출하여 관련된 쿼리 캐시를 무효화하는 것입니다. 이를 통해 데이터 변경 후 화면을 최신 상태로 자동 동기화할 수 있습니다.

• onError: 뮤테이션이 실패했을 때 실행되는 콜백입니다. 사용자에게 에러 메시지를 보여주거나, 에러 로그를 수집하는 등의 작업을 처리합니다.

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

type Post = { id: number; title: string; };
type NewPost = { title: string; };

type UseAddPostMutationOptions = Omit<
  UseMutationOptions<Post, Error, NewPost>,
  'mutationFn'
>;

export const useAddPostMutation = (options?: UseAddPostMutationOptions) => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: addPost,
    
    // 성공 처리 로직
    onSuccess: () => {
      console.log('게시물 추가 성공!');
      queryClient.invalidateQueries({ queryKey: ['posts'] });
    },

    // 에러 처리 로직
    onError: (error) => {
      console.error('게시물 추가 실패:', error.message);
    },
    
    ...options,
  });
};

5. TanStack Query 똑똑하게 사용하기 🧐

5.1. 핵심원칙: 모든 Query와 Mutation을 커스텀 훅으로 감싸라

5.2. Query Key는 명확해야하고 동적으로 관리해라

• 계층적으로 구성
• ['todos', 'list', {status: 'done'}] 처럼 어떤 데이터인지 명확히 알 수 있게 만들어야 합니다.

• 의존성 포함
• 쿼리가 특정 변수에 의존한다면, 반드시 Query Key에 포함시켜야 해당 변수가 변경될 때 쿼리가 다시 실행됩니다.

// hooks/useTodoQuery.ts 
// todo 도메인과 관련된 QueryKey Factory
const todoKeys = {
  all: ['todos'] as const,
  lists: () => [...todoKeys.all, 'list'] as const,
  list: (filters: string) => [...todoKeys.lists(), { filters }] as const,
  details: () => [...todoKeys.all, 'detail'] as const,
  detail: (id: number) => [...todoKeys.details(), id] as const,
}

// GET /todos?status={status}
export function useTodoListQuery(filters: { status: string }) {
  return useQuery({
    // filters 객체가 변경되면 queryKey가 바뀌어 refetch됨 (이 예시가 의존성의 예시)
    queryKey: todoKeys.list(filters.status),
    queryFn: () => fetchTodoList(filters),
  });
}

// GET /todos/{id}
export function useTodoDetailQuery(id: number) {
  return useQuery({
    queryKey: todoKeys.detail(id),
    queryFn: () => fetchTodoById(id),
    enabled: !!id, // id 값이 있을 때만 쿼리 실행
  });
}

5.3. useMutation은 이렇게 사용해라

// hooks/useAddTodoMutation.ts
export function useAddTodoMutation() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (newTodo: NewTodo) => addTodo(newTodo),
    // 성공 시 onSuccess 콜백 실행
    onSuccess: () => {
      // 'todos'로 시작하는 모든 쿼리를 무효화
      queryClient.invalidateQueries({ queryKey: todoKeys.all });
    },
    onError: (error) => {
      // 에러 처리 로직 (사용자에게 Toast 메시지 표시, 로깅 등등..)
      console.error("Todo 추가 실패:", error);
    }
  });
}

// components/AddTodoForm.tsx
function AddTodoForm() {
  const { mutate, isPending } = useAddTodoMutation();

  const handleSubmit = (newTodo: NewTodo) => {
    mutate(newTodo);
  };
  // ...
}

🍯 UX를 극대화하는 Optimistic Updates(낙관적 업데이트)

// hooks/useUpdateTodoMutation.ts
export function useUpdateTodoMutation() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: updateTodo,
    // 1. Mutation이 시작되기 직전에 실행
    onMutate: async (updatedTodo) => {
      // 진행 중인 refetch를 취소 (낙관적 업데이트를 덮어쓰지 않도록)
      await queryClient.cancelQueries({ queryKey: todoKeys.lists() });

      // 이전 데이터 스냅샷
      const previousTodos = queryClient.getQueryData<Todo[]>(todoKeys.lists());

      // 새로운 값으로 캐시를 낙관적으로 업데이트
      queryClient.setQueryData(todoKeys.lists(), (old) =>
        old?.map(todo => todo.id === updatedTodo.id ? updatedTodo : todo)
      );

      // context에 이전 데이터 스냅샷을 반환
      return { previousTodos };
    },
    // 2. Mutation 실패 시 실행
    onError: (err, updatedTodo, context) => {
      // onMutate에서 반환된 context를 사용해 데이터 롤백
      if (context?.previousTodos) {
        queryClient.setQueryData(todoKeys.lists(), context.previousTodos);
      }
      // 에러 UI 처리
    },
    // 3. 성공/실패 여부와 관계없이 Mutation 완료 후 항상 실행
    onSettled: () => {
      // 최신 서버 데이터와 동기화
      queryClient.invalidateQueries({ queryKey: todoKeys.lists() });
    },
  });
}

마무리