TanStack Query 사용해보기

https://ldd6cr-adness.tistory.com/303

Tanstack Query는 뭘까

목차1. TanStack Query란2. 설치 및 기본 설정 2-1. TanStack 패키지 설치 2-2. Query Client 생성 및 Provider 설정3. 데이터 조회 (Fetching)4. 데이터 변경 (Mutations)5. 쿼리 무효화 및 리패칭6. 기타 기능들7. 툴1. TanSt

ldd6cr-adness.tistory.com

0. 실습 프로젝트 내용

게시판 뷰어 : 게시글 목록을 불러오고, 상세 내용을 확인함
기술 스택
- React
- TanStack Query
- JSONPlaceholder API (/posts, /posts/:id, /posts/:comment)
- React Router
프로젝트 구조
- src/
  -- App.tsx
  -- index.tsx
  -- components/
  ㄴ PostList.tsx
  ㄴ PostDetail.tsx
  ㄴ CommentForms
  -- api/
  ㄴ posts.ts
  ㄴ comments.ts

2. 기본 설정

2-1. 기본 설치

npm install
npm install @tanstack/react-query react-router-dom

npm 패키지를 설치하고, tanstak과 페이지 이동을 위한 react-router-dom을 설치했다.

2-2. 라우팅 설정

import React from 'react';
import {Route, Routes} from 'react-router-dom';
import { PostList } from './components/PostList.tsx';
import { PostDetail } from './components/PostDetail.tsx';

function App() {
  return (
    <div>
      <h1 style={{ color: 'black', textAlign: 'center' }}>게시판</h1>
      <Routes>
        <Route path="/" element={<PostList />} />
        <Route path="/posts/:id" element={<PostDetail />} />
        </Routes>
    </div>
  );
}

export default App;

이 부분 화면이 안나와서 보니까 처음엔 div가 아니라 BrowserRouter로 감싸고 있었는데,

index.tsx에서 이미 BrowserRouter로 감싸서 이중으로 감싸버리는 바람에 화면이 안나왔던 거였다.

** BrowserRouter는 항상 애플리케이션의 최상위에 위치하게 하며, 여러 번 사용하지 않도록 하자~ **

2-3. TanStack Query 기본 설정

// index.tsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { BrowserRouter as Router } from 'react-router-dom';

const queryClient = new QueryClient();
const root = ReactDOM.createRoot(document.getElementById('root'));

root.render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <Router>
        <App />
      </Router>
    </QueryClientProvider>
  </React.StrictMode>
);

애플리케이션의 진입점인 index.tsx 파일에 QueryClient, QueryClientProvider를 지정한다.

QueryClient 인스턴스 생성: TanStack Query가 상태, 캐시, 리패치 등 다양한 기능을 관리할 수 있도록 함

QueryClientProvider 컴포넌트: React 컴포넌트 트리 전체에서 TanStack Query 훅이 작동하도록 QueryClient 전달

데이터 관리를 전역에서 하기 위해 QueryClientProvider를 최상위 컴포넌트(App) 외부에 둔다.

기본적인 부분들을 작성했으니 이제 본격적으로 TanStack Query를 사용해볼 시간~!

1. useQuery로 데이터 조회(fetching)

1. API 함수 정의

// api/posts.ts

export const fetchPosts = async () => {
  const response = await fetch('https://jsonplaceholder.typicode.com/posts');
  if (!response.ok) {
    throw new Error('failed to fetch posts');
  }
  return response.json();
}

export const fetchPostById = async (id: number) => {
  const response = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`);
  if (!response.ok) {
    throw new Error('failed to fetch post by id');
  }
  return response.json();
}

posts와 관련된 요청을 정의한 파일이다.

fetchPosts : 모든 게시글 목록을 서버에 요청해서 받아오는 함수

jsonplaceholder 서버에 요청하여 데이터를 받고, js 객체로 변환한다.

fetchPostById : 특정 ID를 가진 게시글 하나만 서버에 요청해서 받아오는 함수

인자 id: number를 통해 숫자 하나(=id)를 입력받는다.

2. PostList 컴포넌트

// components/PostList.tsx

import React from 'react';
import { useQuery } from '@tanstack/react-query';
import { fetchPosts } from "../api/posts.ts";
import { Link } from "react-router-dom";

export function PostList() {
    const { data, isLoading, error } = useQuery({
        queryKey: ['posts'],
        queryFn: fetchPosts,
    });

    if (isLoading) return <p>Loading...</p>;
    if (error instanceof Error) return <p>error: {error.message}</p>;

    return (
        <ul>
            {data.slice(0, 10).map((post: any) => (
                <li key={post.id}>
                    <Link to={`/posts/${post.id}`}>{post.title}</Link>
                </li>
            ))}
        </ul>
    )
}

fetchPosts api 함수로 서버로부터 받아온 값을 post 제목 10개를 띄우는 컴포넌트이다.

useQuery 훅을 사용하여 서버에 요청해 데이터를 가져오고, 상태를 자동으로 관리한다.

queryKey: ['posts'] => 이 요청의 이름표로, TanStack Query가 'posts'를 기억해서 나중에 다시 사용할 수 있다.

queryFn: fetchPosts => 실제로 데이터를 가져오는 함수로, 정의해둔 fetchPosts를 사용한다.

useQuery 훅이 기본 제공하는 속성인 isLoading과 error 속성들을 사용해서 해당 상태일 경우 보여줄 컨텐츠를 작성한다.

3. PostDetail 컴포넌트

import {useParams} from 'react-router-dom';
import {useQuery} from '@tanstack/react-query';
import { fetchPostById } from '../api/posts.ts';
import React from 'react';

export function PostDetail() {
    const {id} = useParams<{ id: string }>();
    const postId = Number(id);

    const { data, isLoading, error } = useQuery({
        queryKey: ['posts', id],
        queryFn: () => fetchPostById(postId!),
        enabled: !!id, // id가 있을 때만 쿼리 실행
    });

    if (isLoading) return <p>Loading...</p>;
    if (error instanceof Error) return <p>error: {error.message}</p>;

    return (
        <div>
            <h2>{data.title}</h2>
            <p>{data.body}</p>
        </div>
    )
}

PostList 컴포넌트와 다르게 key로 id도 같이 사용한다.

또한 enabled 속성을 사용하여 id가 존재할 때만 쿼리를 실행하도록 했다.

결과 화면

2. useMutation으로 데이터 변경

1. API 함수 정의 : 댓글 작성

// api/comments.ts

export const postComment = async (comment: {
  postId: number;
  name: string;
  body: string;
}) => {
  const response = await fetch(
    "https://jsonplaceholder.typicode.com/comments",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(comment),
    }
  );

  if (!response.ok) {
    throw new Error("Failed to post comment");
  }

  return response.json();
};

- 외부 API에 댓글 POST를 요청하고 저장하는 함수다.

jsonplaceholder 샘플 API는 (comment: {postId: number; name: string; body: string }) 구조로 데이터를 받는다.

해당 형식은 jsonplaceholder 웹에서 확인할 수 있다.

각 속성들은 아래와 같은 데이터를 나타낸다.

postId => 어떤 글(post)에 대한 댓글인지
name => 댓글 작성자의 이름
body => 댓글 내용

method: "POST"

: 데이터를 보낸다. 데이터를 받아올 때는 "GET"을 사용한다.

headers; { "Content-Type: "application/json" }

: JSON 형식으로 요청함을 서버에 알려준다.

body: JSON.stringify(comment)

우리가 만든 comment 객체(json 형태)를 문자로 변환

2. 댓글 작성 폼 컴포넌트 생성

// components/CommentForm.tsx

import React, { useState } from "react";
import { useMutation } from "@tanstack/react-query";
import { postComment } from "../api/comments";

interface CommentFormProps {
  postId: number;
}

export function CommentForm({ postId }: CommentFormProps) {
  const [name, setName] = useState("");
  const [body, setBody] = useState("");

  const mutation = useMutation({
    mutationFn: postComment,
    onSuccess: (data) => {
      alert("댓글이 등록되었습니다👏");
      console.log(data); // 응답 확인
      setName("");
      setBody("");
    },
    onError: (error: Error) => {
      alert(`error: ${error.message}`);
    },
  });

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    mutation.mutate({ postId, name, body });
  };

  return (
    <form onSubmit={handleSubmit}>
      <h3>add Comment</h3>
      <input
        type="text"
        placeholder="name"
        value={name}
        onChange={(e) => setName(e.target.value)}
        required
      />
      <br />
      <textarea
        placeholder="add your comment"
        value={body}
        onChange={(e) => setBody(e.target.value)}
        required
      />
      <br />
      <button type="submit" disabled={mutation.isPending}>
        write
      </button>
    </form>
  );
}

3. PostDetail에 댓글 작성 폼 추가

import { useParams } from "react-router-dom";
import { useQuery } from "@tanstack/react-query";
import { fetchPostById } from "../api/posts.ts";
import React from "react";
import { CommentForm } from "./CommentForm.tsx";

export function PostDetail() {
  const { id } = useParams<{ id: string }>();
  const postId = Number(id);

  const { data, isLoading, error } = useQuery({
    queryKey: ["posts", id],
    queryFn: () => fetchPostById(postId!),
    enabled: !!id, // id가 있을 때만 쿼리 실행
  });

  if (isLoading) return <p>Loading...</p>;
  if (error instanceof Error) return <p>error: {error.message}</p>;

  return (
    <div>
      <h2>{data.title}</h2>
      <p>{data.body}</p>
      <CommentForm postId={postId} /> {/*댓글 추가 폼 */}
    </div>
  );
}

결과 화면

3. 메서드를 사용하여 쿼리 무효화/리패칭 구현

1. api 함수 createPost 정의

// api/posts.ts
// ...
export const createPost = async (newPost: { title: string; body: string; userId: number }) => {
  const response = await fetch('https://jsonplaceholder.typicode.com/posts', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(newPost),
  });

  if(!response.ok) {
    throw new Error('failed to create post');
  }
  return response.json();
};

2. PostList.tsx에서 queryClient.invalidateQueries를 사용하여 데이터 무효화+자동리패칭

// components/PostList.tsx
import React from 'react';
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';	// 게시글 목록 수정을 위해 훅 import
import { fetchPosts, createPost } from "../api/posts.ts";	// 필요한 api 함수 createPost import
import { Link } from "react-router-dom";


export function PostList() {
	// queryClient 훅 사용을 위해 queryClient 정의
    const queryClient = useQueryClient();

    // 게시글 목록 가져오기
    const { data, isLoading, error } = useQuery({
        queryKey: ['posts'],
        queryFn: fetchPosts,
    });

    // 게시글 추가 mutation
    const mutation = useMutation({
        mutationFn: createPost,
        onSuccess: () => {
            // 게시글 추가후 posts 쿼리 무효화 및 (자동)리패치
            queryClient.invalidateQueries({queryKey:['posts']});
            alert('Post added successfully!👏');
        },
    });

    const handleAddPost = () => {
        const newPost = {
            title: 'New Post',
            body: 'This is a new post.',
            userId: 1,
        };
        mutation.mutate(newPost);
    };

    if (isLoading) return <p>Loading...</p>;
    if (error instanceof Error) return <p>error: {error.message}</p>;

    return (
        <div>
            <h1>Post List</h1>
            <button onClick={handleAddPost}>Add Post</button>
        <ul>
            {data.slice(0, 10).map((post: any) => (
                <li key={post.id}>
                    <Link to={`/posts/${post.id}`}>{post.title}</Link>
                </li>
            ))}
        </ul>
        </div>
    )
}

결과 화면

4. 데이터의 신선도와 캐시 유지 시간 설정

1. staleTime, cacheTime 옵션으로 데이터의 신선도 및 캐시 유지 시간을 설정할 수 있다

첫 마운트 시, 로그 확인(요청 발생)이 된다.

staleTime
- 1000*5(5초) 동안은 데이터가 신선한 것으로 간주되어, 페이지를 벗어났다가 5초 안에 들어오면 요청이 없다.
- staleTime을 설정하지 않을경우, 페이지를 벗어났다 돌아올 때마다 항상 요청이 발생한다(fetchPosts 호출)
cacheTime
- 캐시된 쿼리 데이터가 15초마다 제거된다.
- 캐시는 쿼리가 종료될 때 바로 제거되나, 위 코드에서는 15초동안은 캐시된 데이터가 메모리에 유지된다.
- React Query Devtools를 사용하면 캐시 상태를 눈으로 확인할 수 있으나, Network 탭에서는 캐시의 제거 여부를 알 수 없다.

5. React Query Devtools

1. 설치

npm install @tanstack/react-query-devtools

2. Devtool 렌더링

// index.tsx ( QueryClientProvider 하위)

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

function App() {
	return (
    	<QueryClientProvider client={queryClient}>
        	{/* application components */}
            <ReactQueryDevtools initialIsOpen={false} />
        </QueryClientProvider>
    );
}

결과 화면

화면 구석에 보이는 TanStack Query DevTool 버튼을 누르면 다음과 같은 화면을 볼 수 있다.

색깔별로 아래와 같은 상태를 나타낸다.

Fresh(초록), Fetching(파랑), Paused(보라), Stale(노랑), Inactive(회색)

즉, 화면을 첫 마운트, 혹은 5초 안에 다시 돌아왔을 때는 posts 요청이 초록색이나, 5초 후에는 노란색이 된다.

첫 화면에서 다른 화면으로 넘어간 후 15초가 지나면(예로 PostLists에서 PostDetails 화면으로)

위 사진과 같이 Inactive 요청(PostLists에서의 요청)이 삭제 = cache 삭제가 된 것을 확인할 수 있다.

🥺문제 생겼던 부분

: 계속 cacheTime에서 에러가 나길래 찾아봤더니 업데이트 해서 이제 cacheTime은 안쓰고 gcTime (garbage collection)을 쓴다고 한다. 삽질...ㅎㅎ

cacheTime으로 작성했을 때는 캐시 삭제가 제대로 안됐는데 gcTime으로 변경하면 잘 된다.

'프론트엔드(Front-end) > Tools' 카테고리의 다른 글

axios는 뭘까 (1)	2025.05.22
Zustand 사용해보기 (0)	2025.05.15
Tanstack Query는 뭘까 (0)	2025.05.08
Zustand는 뭘까 (0)	2025.04.04
Next.js는 뭘까 (0)	2025.03.20

🥔감자의 오묘한 모험🥔

TanStack Query 사용해보기

목차

0. 실습 프로젝트 내용

2. 기본 설정

1. useQuery로 데이터 조회(fetching)

2. useMutation으로 데이터 변경

3. 메서드를 사용하여 쿼리 무효화/리패칭 구현

4. 데이터의 신선도와 캐시 유지 시간 설정

5. React Query Devtools

'프론트엔드(Front-end) > Tools' 카테고리의 다른 글

티스토리툴바

TanStack Query 사용해보기

목차

0. 실습 프로젝트 내용

2. 기본 설정

1. useQuery로 데이터 조회(fetching)

2. useMutation으로 데이터 변경

3. 메서드를 사용하여 쿼리 무효화/리패칭 구현

4. 데이터의 신선도와 캐시 유지 시간 설정

5. React Query Devtools

'프론트엔드(Front-end) > Tools' 카테고리의 다른 글

관련글

티스토리툴바