TanStack Query 수동 캐시 정규화: 목록·상세 동기화와 선택 기준

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

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

• 시작본 다운로드 — query-step-10-optimistic.zip
• 완료본 다운로드 — query-step-11-normalization.zip

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

시작본에서 직접 바꾸기

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

1. app/tasks/TaskItem.tsx — 기존 파일의 같은 위치를 갱신합니다.

변경 이유와 결과: 성공한 Task 응답으로 목록·상세 캐시를 함께 갱신합니다. 필터별 소속은 invalidation으로 서버 결과를 다시 확인하며 정규화 저장소라고 과장하지 않습니다.

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

app/tasks/TaskItem.tsx 전체 파일

'use client';
import { useState } from 'react';
import { useMutation, useQueryClient } from '@tanstack/react-query';
import type { Task } from '../lib/types';
import { updateTask } from '../lib/tasks-api';
import { taskKeys } from '../lib/task-keys';
export default function TaskItem({ task, onSelect }: { task: Task; onSelect: (id: string) => void }) {
  const [fail, setFail] = useState(false);
  const client = useQueryClient();
  const mutation = useMutation({
    mutationFn: (completed: boolean) => updateTask(task.id, completed, fail),
    onMutate: async (completed) => {
      await client.cancelQueries({ queryKey: taskKeys.all });
      const lists = client.getQueriesData<Task[]>({ queryKey: taskKeys.lists() });
      const detail = client.getQueryData<Task>(taskKeys.detail(task.id));
      client.setQueriesData<Task[]>({ queryKey: taskKeys.lists() }, (rows) => rows?.map((row) => row.id === task.id ? { ...row, completed } : row));
      if (detail) client.setQueryData(taskKeys.detail(task.id), { ...detail, completed });
      return { lists, detail };
    },
    onError: (_error, _variables, context) => {
      for (const [key, rows] of context?.lists ?? []) client.setQueryData(key, rows);
      if (context?.detail) client.setQueryData(taskKeys.detail(task.id), context.detail);
    },
    onSuccess: (updated) => {
      client.setQueryData(taskKeys.detail(updated.id), updated);
      client.setQueriesData<Task[]>({ queryKey: taskKeys.lists() }, (rows) => rows?.map((row) => row.id === updated.id ? updated : row));
    },
    onSettled: () => client.invalidateQueries({ queryKey: taskKeys.all }),
  });
  return (
    <li>
      <button onClick={() => onSelect(task.id)}>{task.title}</button>
      <button disabled={mutation.isPending} onClick={() => mutation.mutate(!task.completed)}>{task.completed ? '완료 취소' : '완료'}</button>
      <label><input type="checkbox" checked={fail} onChange={(event) => setFail(event.target.checked)} />실습 전환 실패</label>
      {mutation.isError && <span role="alert">{mutation.error.message}</span>}
    </li>
  );
}

완료 확인

1. 시작본은 직전 완료본과 동일한 ZIP입니다. 압축을 푼 뒤 npm ci로 잠금 파일의 의존성을 설치합니다.
2. npm run dev 실행 후 http://localhost:3000/tasks를 엽니다.
3. 성공한 Task 응답으로 목록·상세 캐시를 함께 갱신합니다. 필터별 소속은 invalidation으로 서버 결과를 다시 확인하며 정규화 저장소라고 과장하지 않습니다.
4. npm run typecheck와 npm run build가 성공하면 다음 프로젝트 단계로 갑니다.

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

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