TanStack Query 데이터가 바뀌었는데 화면이 갱신되지 않는 이유에서 먼저 확인할 것
TanStack Query 데이터가 바뀌었는데 화면이 갱신되지 않는 이유는 증상만 보고 바로 고치기보다 실행 환경, 설정, 데이터 형태를 나눠 확인해야 합니다. 서버 데이터는 바뀐 것 같은데 화면의 query 결과가 갱신되지 않는 상황을 기준으로 원인을 좁히고, mutation 후 갱신 기준을 확인합니다.
증상부터 정확히 보기
TanStack Query 데이터가 바뀌었는데 화면이 갱신되지 않는 이유를 만났을 때는 에러 문구를 그대로 검색하기 전에 어느 단계에서 문제가 발생했는지 확인합니다. 작성한 코드가 잘못된 것인지, 설정이 누락된 것인지, 실행 환경이 다른 것인지에 따라 해결 방법이 달라집니다.
특히 TanStack Query 작업에서는 로컬 개발 환경에서는 보이지 않던 문제가 빌드, 배포, 브라우저 실행 시점에서 드러날 수 있습니다. 그래서 작은 예시로 재현하고, 어떤 조건에서만 문제가 생기는지 먼저 좁히는 것이 좋습니다.
문제가 생기는 이유
이 문제의 핵심은 서버 데이터는 바뀐 것 같은데 화면의 query 결과가 갱신되지 않는 상황입니다. 단순 오타일 때도 있지만, 대부분은 도구가 코드를 해석하는 방식과 개발자가 기대한 동작이 어긋난 데서 출발합니다.
해결책을 붙이기 전에 값의 형태, 설정 파일 위치, 실행 시점, 권한 조건을 분리해서 보면 불필요한 수정이 줄어듭니다. 같은 에러라도 프로젝트 구조에 따라 원인이 달라질 수 있습니다.
코드와 설정에서 고치는 방법
아래 예시는 문제를 확인할 때 볼 수 있는 최소 형태입니다. 실제 프로젝트에서는 파일 위치와 데이터 이름이 다를 수 있으니 구조만 기준으로 보면 됩니다.
const queryClient = useQueryClient(); const mutation = useMutation({ mutationFn: updateProduct, onSuccess: () => { queryClient.invalidateQueries({ queryKey: ['products'] }); }});수정 후에는 결과 화면만 보지 말고 왜 이 방식이 문제를 줄이는지 확인해야 합니다. 그래야 비슷한 문제가 다른 페이지나 빌드 환경에서 반복될 때 빠르게 찾을 수 있습니다.
수정 후 확인할 체크리스트
수정이 끝났다면 새로고침, 개발 서버 재시작, 빌드, 실제 데이터 조건을 함께 확인합니다. 한 화면에서만 맞고 다른 조건에서 다시 깨지는 경우가 많기 때문입니다.
마지막으로 임시 회피 코드가 남아 있지 않은지 봅니다. 타입 단언, 무조건적인 클라이언트 처리, 권한 완화, 넓은 도메인 허용처럼 문제를 숨기는 코드는 이후 유지보수에서 더 큰 문제로 이어질 수 있습니다.
정리
TanStack Query 데이터가 바뀌었는데 화면이 갱신되지 않는 이유는 한 가지 정답 코드보다 확인 순서가 중요합니다. 증상, 원인, 수정 위치, 재발 방지 기준을 나눠두면 다음에 같은 유형의 문제를 만났을 때 훨씬 빠르게 대응할 수 있습니다.