TanStack Query 페이지네이션 실습: placeholderData로 이전 목록 유지하기

중간부터 시작하는 전체 실습 파일

기존 Next.js Route Handler TaskFlow의 /tasks 화면과 /api/tasks를 이어서 확장합니다. 인증 없는 demo 메모리 저장소를 사용하는 로컬 실습이며 계정·외부 DB·API 키가 필요 없습니다. MSW를 활성화하지 않습니다. 서버를 다시 시작하면 데이터가 초기화됩니다.

• 시작본 다운로드 — query-step-07-invalidation.zip
• 완료본 다운로드 — query-step-08-pagination.zip

이 글의 시작본은 직전 프로젝트 단계 완료본 전체입니다. 이미 직전 단계를 마쳤다면 그 폴더를 이어 쓰셔도 됩니다. Node.js 24.x와 npm을 사용하며 패키지 버전은 package-lock.json에 고정했습니다.

시작본에서 직접 바꾸기

시작본을 실행한 뒤 아래 변경 파일을 순서대로 수정합니다. 완료본의 같은 경로 파일에는 import와 입력 타입을 포함한 전체 코드가 있습니다.

1. app/api/tasks/route.ts — 기존 파일의 같은 위치를 갱신합니다.
2. app/tasks/PaginatedTaskList.tsx — 이전 단계에 없던 파일을 만듭니다.
3. app/tasks/TaskDashboard.tsx — 기존 파일의 같은 위치를 갱신합니다.

변경 이유와 결과: GET의 page/pageSize 계약과 PaginatedTaskList를 추가합니다. 이전 데이터 placeholder 동안 다음 버튼을 막고 마지막 페이지에서 종료합니다.

완료본의 docs/changes.patch에서 시작·완료 차이를, docs/current-step.md에서 파일별 적용 위치를 확인할 수 있습니다. 아래 전체 파일을 같은 경로에 반영한 다음 실행하세요.

app/api/tasks/route.ts 전체 파일

import { listTasks, addTask } from '@/app/lib/store';
export async function GET(request: Request) {
  const params = new URL(request.url).searchParams;
  if (params.get('fail') === '1') return Response.json({ message: '실습 조회 실패' }, { status: 500 });
  const status = params.get('status') ?? 'all';
  if (!['all', 'active', 'completed'].includes(status)) return Response.json({ message: '필터 오류' }, { status: 400 });
  const rows = listTasks('demo').filter((task) => status === 'all' || (status === 'completed' ? task.completed : !task.completed));
  if (params.has('page') || params.has('cursor')) {
    const size = Number(params.get('pageSize') ?? '2');
    if (!Number.isInteger(size) || size < 1 || size > 50) return Response.json({ message: 'pageSize 오류' }, { status: 400 });
    if (params.has('cursor')) {
      const cursor = params.get('cursor') ?? '';
      const offset = cursor === '' ? 0 : rows.findIndex((task) => task.id === cursor) + 1;
      if (cursor && offset === 0) return Response.json({ message: 'cursor 오류' }, { status: 400 });
      const items = rows.slice(offset, offset + size);
      return Response.json({ items, nextCursor: offset + size < rows.length ? items.at(-1)!.id : null }, { headers: { 'Cache-Control': 'private, no-store' } });
    }
    const page = Number(params.get('page'));
    if (!Number.isInteger(page) || page < 1) return Response.json({ message: 'page 오류' }, { status: 400 });
    return Response.json({ items: rows.slice((page - 1) * size, page * size), page, totalPages: Math.max(1, Math.ceil(rows.length / size)) }, { headers: { 'Cache-Control': 'private, no-store' } });
  }
  return Response.json(rows, { headers: { 'Cache-Control': 'private, no-store' } });
}
export async function POST(request: Request) {
  try {
    const body: unknown = await request.json();
    if (!body || typeof body !== 'object' || !('title' in body)) throw new Error('제목 필요');
    if ('simulateFailure' in body && body.simulateFailure === true) return Response.json({ message: '실습 저장 실패' }, { status: 503 });
    return Response.json(addTask('demo', body.title), { status: 201 });
  } catch {
    return Response.json({ message: '올바른 JSON과 2~100자 제목이 필요합니다.' }, { status: 400 });
  }
}

app/tasks/PaginatedTaskList.tsx 전체 파일

 'use client';
import { useState } from 'react';
import { keepPreviousData, useQuery } from '@tanstack/react-query';
import { getTaskPage } from '../lib/tasks-api';
import { taskKeys } from '../lib/task-keys';
export default function PaginatedTaskList() {
  const [page, setPage] = useState(1);
  const query = useQuery({ queryKey: taskKeys.page(page), queryFn: ({ signal }) => getTaskPage(page, signal), placeholderData: keepPreviousData });
  return (
    <section aria-label="페이지 목록">
      <h2>페이지 목록</h2>
      {query.isPending ? <p>페이지 로딩 중</p> : query.isError ? <p role="alert">{query.error.message}</p> : <ul>{query.data.items.map((task) => <li key={task.id}>{task.title}</li>)}</ul>}
      <p>페이지 {page} {query.isPlaceholderData ? '(이전 목록 유지 중)' : ''}</p>
      <button disabled={page === 1 || query.isFetching} onClick={() => setPage((value) => value - 1)}>이전 페이지</button>
      <button disabled={!query.data || query.isFetching || query.isPlaceholderData || page >= query.data.totalPages} onClick={() => setPage((value) => value + 1)}>다음 페이지</button>
    </section>
  );
}

app/tasks/TaskDashboard.tsx 전체 파일

'use client';
import { useState } from 'react';
import TaskListClient from './TaskListClient';
import type { TaskStatus } from '../lib/tasks-api';
import TaskDetailClient from './TaskDetailClient';
import TaskForm from './TaskForm';
import QueryStatePanel from './QueryStatePanel';
import PaginatedTaskList from './PaginatedTaskList';
export default function TaskDashboard() {
  const [status, setStatus] = useState<TaskStatus>('all');
  const [selected, setSelected] = useState<string | null>(null);
  return (
    <main>
      <h1>TaskFlow Query</h1>
      <label>필터 <select value={status} onChange={(event) => setStatus(event.target.value as TaskStatus)}>
        <option value="all">전체</option><option value="active">진행 중</option><option value="completed">완료</option>
      </select></label>
      <TaskForm />
      <TaskListClient status={status} onSelect={setSelected} />
      {selected && <TaskDetailClient taskId={selected} />}
      <QueryStatePanel />
      <PaginatedTaskList />
    </main>
  );
}

완료 확인

1. 시작본은 직전 완료본과 동일한 ZIP입니다. 압축을 푼 뒤 npm ci로 잠금 파일의 의존성을 설치합니다.
2. npm run dev 실행 후 http://localhost:3000/tasks를 엽니다.
3. GET의 page/pageSize 계약과 PaginatedTaskList를 추가합니다. 이전 데이터 placeholder 동안 다음 버튼을 막고 마지막 페이지에서 종료합니다.
4. npm run typecheck와 npm run build가 성공하면 다음 프로젝트 단계로 갑니다.

기존 체크포인트 검증 기록: TypeScript 검사·프로덕션 빌드와 실제 소스를 사용한 JSDOM/상태 시나리오 검증을 통과한 기록입니다. 별도 실제 브라우저 화면 검수는 그 파일 검증 범위에 포함하지 않았습니다. 이번 문장 보완에서 재실행한 결과는 아닙니다.

아래 부분 예제는 핵심 변경을 설명합니다. 실행에 필요한 전체 파일과 보조 타입·API는 위 완료본에서 확인하세요.