TanStack Query란?

• 웹 서비스를 위한 Data Fetching 라이브러리

등장 배경

• 대부분 웹 프레임워크는 데이터를 전체적으로 조회하거나 관리하는 것에 대한 명확한 방법을 제공하지 않음
• 그렇기에 상태 관리 라이브러리를 사용하기도 함(Zustand)
• 대부부분의 상태 관리 라이브러리는 클라이언트에서의 상태를 관리하는 데에 뛰어남!🫅
• 하지만 서버 상태를 관리하는 데에는 효과적이지 않음😭
• 서버 상태의 특성
  • 캐싱
    • 중복 요청 제거
    • 오래된 데이터 업데이트
    • 데이터가 가져온지 오래된 시점을 파악
  • 성능 최적화
  • 메모리 관리 및 GC

• TanStack Query는 서버 상태를 관리하는 최고의 라이브러리
  • 최고인 이유?
    • 세팅 용이
    • 커스텀 용이
    • 데이터 관리 용이
• 사용하면 좋은점
  • 캐싱 및 성능 최적화를 코드 몇 줄로 대체 가능
  • 유지보수 용이
  • 통신 속도 증가로 인한 사용자 경험 상승
  • 대역폭 절약 및 메모리 성능 향상

주요 개념

Query란?

• 데이터를 가져오는 행위를 ‘쿼리’라고 부름
• 이 행위를 위해 useQuery 훅을 사용
• Query Key: 캐시를 관리하기 위한 이름표
• Query Function: 실제로 fetch나 axios 등 데이터를 가져오는 비동기 함수

Mutation란?

• 데이터를 변경하는 행위를 ‘뮤테이션’이라고 부름(생성, 수정, 삭제)
• 이 행위를 위해 useMutation 훅을 사용
• Mutation Key(선택): 뮤테이션 식별 및 로딩 상태 추적을 위한 key
• Mutation Function: 실제로 fetch나 axios 등 데이터를 변경하는 비동기 함수

Query Invalidation이란?

• 캐시된 데이터를 '무효화'하여 다시 가져오도록 하는 행위를 '쿼리 무효화'라고 부름
• 주로 뮤테이션 성공 후 관련된 쿼리를 최신 상태로 업데이트하기 위해 사용
• queryClient.invalidateQueries()를 통해 특정 Query Key의 캐시를 stale 상태로 만듦
• 무효화된 쿼리는 자동으로 refetch되어 최신 데이터를 가져옴

동작 원리

useQuery

const { data } = useQuery({
	queryKey: ['user']
	queryFn: async () => (await fetch('url').json()
	}

• ‘user’라는 key로 api 호출
• key가 캐시된 데이터를 사용할지 다시 호출을 할지 결정하는 기준

• 캐시된 데이터가 없다면 호출 함수를 실행하여 서버로부터 데이터를 받아옴
• 그 데이터가 캐시되고 이후 요청에서는 캐시된 데이터 사용 가능
• Miss 상황이라고 부름

• 서버에 요청을 전송하지 않고, 캐시된 데이터 사용
• 같은 데이터를 가져오는 요청이 여러 번 발생해도, 캐시된 데이터를 사용하게 되어 중복 요청량 감소
• Hit 상황이라고 부름

데이터의 신선도

• Tanstack Query는 캐시한 데이터를 Fresh한 데이터와 Stale 데이터로 구분하여 관리
• 캐시된 데이터가 Fresh 상태라면 캐시데이터 사용, Stale한 상태라면 서버로 요청

캐싱된 데이터의 사용 가능 기간을 지정하는 방법

• staleTime 옵션으로 지정이 가능
• isStale로 상태 확인 가능

const { data, isStale } = useQuery({
	queryKey: ['user']
	queryFn: async () => (await fetch('url').json()

• staleTime 100초
• 100초 뒤에 호출하면 isStale이 true로 변경

설치 및 구성

npm i @tanstack/react-query
# or
pnpm add @tanstack/react-query
# or
yarn add @tanstack/react-query

• 우리는 npm을 사용하자

npm i -D @tanstack/eslint-plugin-query
# or
pnpm add -D @tanstack/eslint-plugin-query
# or
yarn add -D @tanstack/eslint-plugin-query

• Tanstack Query 코드를 작성하면서 버그 및 문법 오류를 잡아주는 eslint 플러그인도 제공

$ npm i @tanstack/react-query-devtools
# or
$ pnpm add @tanstack/react-query-devtools
# or
$ yarn add @tanstack/react-query-devtools

• Tanstack Query의 모든 내부 동작을 시각화해주는 도구

Provider 세팅

• Tanstack Query도 내부적으로 React Context로 구성
• 프로젝트에서 Tanstack Query에서 제공하는 hook을 사용하기 위한 Provider 세팅 필요

import {
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'

const queryClient = new QueryClient()

export default function App() {

• new QueryClient를 생성하면 쿼리 캐시 저장소가 생성
• Tanstack Query 패키지에서 제공되는 useQuery와 같은 hook들은 Provider로 제공된 캐시 저장소에서 사용
• queryClient 저장소 생성 ⇒ queryClientProvider로 랩핑 ⇒ 프로젝트 내부에 컴포넌트에서 해당 저장소에 접근 가능 ⇒ hooks 사용 ⇒ Provider로 제공된 캐시 저장소에서 사용됨

핵심 기능

useQuery

• 가장 기본적인 쿼리 hook
• 데이터를 가져올 때 사용

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

type ResponseValue = {
  message: string
  time: string
}

export default function DelayedData() {
  const

• time과 message가 data 객체로 오는 api
• data가 아닌 query 결과 전체를 불러오면 아래와 같은 형식으로 응답

• 데이터가 아직 없는 상태
• "쿼리가 아직 시작 안 했거나, 첫 데이터를 받기 전"

• 로딩 중 + 캐시 없음
• "데이터를 가져오는 중이고, 보여줄 캐시도 없는 상태"

• 성공적으로 데이터를 받음
• "쿼리가 성공하고 데이터가 있는 상태"

• 에러 발생
• "쿼리 실행 중 에러가 발생한 상태"

const { data, isLoading, isError, error } = useQuery({...});

if (isLoading) return <Spinner />; // 로딩 스피너 컴포넌트
if (isError

• 상태에 따른 처리 용이

useQuery 옵션

주요 옵션

• queryKey
  • 고유한 쿼리 식별자
  • 배열로 전송(다중 키 가능)
  • 필수 옵션
• queryFn
  • 데이터를 가져오는 함수, 데이터 반환 or 오류 쓰로잉 필수
  • 필수 옵션
• select
  • 가져온 데이터 변형 가능
  • 최종 데이터 타입을 3번째 제네릭 타입으로 선언 가능
• enabled
  • 쿼리 자동 실행 여부 옵션
  • false인 경우, 대기 상태(pending)로 시작
• retry
  • 쿼리 실패 시 재시도 횟수
• staleTime
  • 데이터가 stale되는데 걸리는 시간

queryKey

• 쿼리 키는 쿼리를 식별하는 고유한 값으로, 배열 형태로 지정
• 다중 쿼리 키를 사용 가능(배열 요소들 순서 중요)

// 단일 아이템 쿼리 키
useQuery({ queryKey: ["Jay"] });

// 다중 아이템 쿼리 키
useQuery({ queryKey: ["Jay", "study", 555, { a:

• queryFn에 props 값이 다르면 별개의 요청을 전송해야 함
• 그렇기 때문에 식별을 위한 key와 queryFn에 들어가는 props를 전부 key로 담아서 전송

function DelayedData({ wait = 1000 }: { wait: number }) {
  const { data } = useQuery<ResponseValue>({
    queryKey: ['delay',

• 만약 key 배열에 props를 안담는다면?
• 매번 다른 값을 담아서 api 호출을 해야 하는데, 식별용 key만 있으니까 이전에 호출해서 받은 캐싱된 데이터로 처리됨!
• eslint에 다음 rules를 추가하면 함수에서 사용된 변수가 key로 지정되지 않았을 때, 에러를 발생시킬 수 있음 "@tanstack/query/exhaustive-deps": "error",

queryFn

• 데이터를 가져오는 비동기 함수
• 데이터 반환 or 오류 쓰로잉 필수
• 쓰로잉한 오류는 반환되는 error로 확인 가능
• error 기본 값은 null

    queryFn: async () => {
      const res = await fetch('https://api.heropy.dev/v0/delay?t=1000')
      const data = await res.json()
      if (!data.time)

select

• 가져온 data를 변형
• 쿼리 함수가 반환하는 데이터를 인수로 받아 변형 시키면 최종 데이터가 됨

  const { data } = useQuery<Users, Error, string[]>({
    queryKey: ['users'],
    queryFn: async () => {
      const

• data에 user.name만 담긴 배열이 반환됨
• 3번째로 담긴 타입이 최종 반환 타입

    "users": [
        {
            "id": "ywTTX",
            "name": "Neo",
            "age": 85,
            "isValid": true,
            "emails": [
                "neo1@heropy.dev"

• 실제 네트워크 요청에 대한 응답은 그대로 오지만
• console.log(data);의 값은 아래와 같이 출력

 ['Neo', 'Trinity', 'Emily', 'John', 'Smith', 'Evan', 'Lewis']

placeholderData

• isPending 상태에서 임시로 표현할 데이터를 지정
• 쿼리 함수가 실행되기 전 상태라면 지정한 데이터가 미리 담겨져 있음

export default function DelayedData() {
  const { data } = useQuery<Users, Error, string[]>({
    queryKey: ["users"],
    queryFn

• console에서 미리 지정된 디폴트 값이 출력되고, query 함수가 호출되어 데이터를 받아오면 반환된 데이터로 변경
• 데이터를 받아오기 전이라 화면이 깨지는 것을 방지하기 위해 사용

useMutation

• 데이터 변경 작업을 위한 useMutation hook 제공
• 데이터 변경 작업을 처리하고 useQuery와 같이 여러 상태를 확인 가능
• useQuery는 ‘가져오기’ / useMutation은 ‘보내기’

useMutation 옵션

onSuccess

• 뮤테이션이 성공했을 때 실행되는 콜백 함수
• 주로 쿼리 무효화에 사용

const mutation = useMutation({
  mutationFn: createPost,
  onSuccess: () => {
    // 게시글 생성 성공 후 실행
    queryClient.invalidateQueries({ queryKey: ['posts'] });

• 캐시된 데이터는 mutation이 발생하기 이전 데이터
• 캐시된 데이터와 수정된 데이터 동기화가 필요함
• 그래서 queryClient 내부에 invalidateQueries 옵션으로 mutation한 key를 넣어서 해당 캐시 데이터를 최신화하는 것
• 쿼리 무효화 흐름

// 1. 현재 캐시된 게시글 목록
posts: [게시글1, 게시글2, 게시글3]

// 2. 새 게시글 생성 (mutation 실행)
mutate({ title: '새 글', content: '...' })
  ↓
// 3. 서버에 POST 요청 성공

Tanstack Query Devtools

• provider 내부에 Devtools 컴포넌트를 삽입

import {
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'

const queryClient = new QueryClient()

• 우측 하단에 전용 개발자 도구 버튼 활성화

• 클릭 시 현재 캐시된 데이터 확인 및 데이터 리프레싱 등을 가능
• Production 모드에서는 사용 불가