애드블럭 종료 후 사이트를 이용해 주세요.

ABOUT ME

-

Today
-
Yesterday
-
Total
-
  • SSR 데이터가 길을 잃는 곳 1편 - HydrationBoundary 위의 useQuery
    Next.js 2026. 11. 17. 07:44
    728x90
    반응형

    Next.js App Router에서 TanStack Query로 서버 prefetch를 쓰는 FE 개발자를 위한 글이다. prefetch를 제대로 했는데도 첫 화면이 폴백으로 그려졌다가 다시 그려진다면, 범인은 데이터를 쓰는 컴포넌트가 아니라 트리 위쪽에 있을 수 있다. HydrationBoundary보다 위에서 같은 쿼리를 useQuery로 구독하면 서버가 보낸 데이터는 SSR HTML에도, 첫 페인트에도 들어가지 않는다.

    서버 레이아웃에서 prefetchQuery로 받은 데이터를 dehydrate로 직렬화해 HydrationBoundary에 넘기는 패턴을 전제로 한다. HydrationBoundary는 이 데이터를 클라이언트 쿼리 캐시에 채운다(hydrate). "조상"은 트리에서 HydrationBoundary를 감싸는 위쪽 컴포넌트를 말한다. 2026년 10월 기준 v5.90 설치본과 저장소 main 소스로 확인했다.

    prefetch를 두 번 넣었는데 화면은 그대로였다

    관리 화면을 하드 리로드하면 사이드바가 일반 사용자용 메뉴 두 개로 그려졌다가 관리자 메뉴로 늘어났고 하단 플랜 카드는 한 박자 늦게 나타났다. 서버 prefetch를 두 번 넣었지만 증상은 그대로였다.

    처음에는 레이아웃의 prefetch 하나가 await 없이 시작된 것을 원인으로 봤다. 그것도 문제였지만(에지 케이스에서 다룬다) 고친 뒤에도 사이드바 메뉴는 첫 렌더에서 pending이었다. 메뉴를 정하는 워크스페이스 목록을 루트의 analytics 프로바이더도 구독하고 있었다. QueryClientProvider 바로 아래, 모든 HydrationBoundary의 조상 자리다. 상담 위젯 SDK를 부팅하는 프로바이더도 같은 자리에서 사용자 정보를 구독했다.

    두 가지 내부 동작이 겹친다

    HydrationBoundary는 서버가 보낸 쿼리를 둘로 나눈다. 캐시에 없는 쿼리는 useMemo 안에서, 즉 렌더 도중에 바로 hydrate 한다. 캐시에 이미 있는 쿼리는 모아 뒀다가 useEffect에서 hydrate 한다. 소스를 줄이면 이런 모양이다.

    // HydrationBoundary 내부 (요약)
    const queue = useMemo(() => {
      for (const q of state.queries) {
        if (!cache.get(q.queryHash)) {
          newQueries.push(q);
        } else if (isNewer(q)) {
          existingQueries.push(q);
        }
      }
      hydrate(client, { queries: newQueries });
      return existingQueries;
    }, [client, state]);
    
    useEffect(() => {
      hydrate(client, { queries: queue });
    }, [client, queue]);

    그리고 useQuery는 렌더 중에 캐시 엔트리를 만든다. 내부 QueryObserver가 옵션을 받으면 queryCache.build()가 캐시에 없는 쿼리를 추가한다. enabled: false여도 요청만 안 보낼 뿐 pending 엔트리는 생긴다.

    렌더는 부모에서 자식으로 내려가니 조상의 useQuery가 엔트리를 먼저 만들고 HydrationBoundary는 그 쿼리의 hydrate를 이펙트로 미룬다. 이펙트는 서버에서 돌지 않고 클라이언트에서도 첫 렌더 뒤에 돈다. prefetch는 성공했는데 결과가 첫 화면에 닿지 못한다.

     

     

    의도된 설계다. 소스 주석에 따르면 transition(useTransition 등으로 표시한 낮은 우선순위 업데이트) 도중 현재 화면의 쿼리가 새 데이터로 바뀌지 않게 하려고 기존 쿼리를 커밋 뒤로 미룬다. 페이지 전환에는 맞지만 첫 로드에서는 조상 구독이 서버 데이터를 막는다. 공식 hydration 레퍼런스와 Advanced SSR 가이드에는 이 분기 설명이 없어서 소비처 코드만 봐서는 찾을 수 없었다.

    조상 한 줄 차이로 재현된다

    설치본으로 renderToString 재현을 만들었다. ['me']를 prefetch 해 dehydrate 하고, 조상 구독 여부만 바꿔 렌더 한 출력이다.

    조상 없음            <p>hello kir</p>
    조상 useQuery        <p>[pending]</p>
    조상 enabled: false  <p>[pending]</p>
    조상을 첫 렌더 뒤로  <p>hello kir</p>

    내 앱에서는 하드 리로드 후 페이지 소스 보기로 SSR HTML을 열어 보면 된다. prefetch 한 데이터 대신 폴백이 들어 있으면 조상부터 의심한다.

    구독을 첫 렌더 뒤로 미뤘다

    규칙을 하나 정했다. HydrationBoundary의 조상은 서버가 prefetch 하는 쿼리를 렌더 중에 구독하지 않는다. 쿼리 구독은 렌더 출력이 없는 자식 컴포넌트로 떼어 하이드레이션이 끝난 뒤에 마운트 한다. 첫 렌더에서 캐시가 비어 있으니 HydrationBoundary가 렌더 도중 데이터를 채우고, 나중에 붙는 자식은 채워진 캐시를 읽는다.

    마운트 감지에 흔히 쓰는 useState(false) + useEffect(() => setMounted(true), [])는 쓸 수 없었다. 이 프로젝트는 React Compiler 대응 규칙인 react-hooks/set-state-in-effect를 error로 두고 eslint-disable도 금지한다. 대신 외부 저장소를 구독하는 훅인 useSyncExternalStore를 썼다. 세 번째 인자인 서버 스냅샷은 서버 렌더와 하이드레이션 렌더에서만 쓰인다. 서버 스냅샷을 false, 클라이언트 스냅샷을 true로 두면 "하이드레이션이 끝났는가"가 된다.

    // useIsHydrated.ts
    'use client';
    import { useSyncExternalStore } from 'react';
    
    // 구독할 외부 저장소가 없으니 아무것도 안 한다
    const subscribe = () => () => {};
    const getSnapshot = () => true;
    const getServerSnapshot = () => false;
    
    // 서버 렌더와 하이드레이션 렌더에서 false,
    // 그 다음 렌더부터 true
    export function useIsHydrated(): boolean {
      return useSyncExternalStore(
        subscribe,
        getSnapshot,
        getServerSnapshot,
      );
    }
    // queries.ts
    import { queryOptions } from '@tanstack/react-query';
    
    export type Me = { id: string; isAdmin: boolean };
    
    export const meQuery = queryOptions({
      queryKey: ['me'],
      queryFn: async (): Promise<Me> => {
        const res = await fetch(`${process.env.API_URL}/me`);
        if (!res.ok) throw new Error(`me ${res.status}`);
        return res.json();
      },
    });
    // AnalyticsProvider.tsx
    'use client';
    import { useEffect, type PropsWithChildren } from 'react';
    import { useQuery } from '@tanstack/react-query';
    
    import { analytics } from './analytics';
    import { meQuery } from './queries';
    import { useIsHydrated } from './useIsHydrated';
    
    // 렌더 출력 없이 구독과 부수효과만 맡는다
    function AnalyticsIdentity() {
      const { data: me } = useQuery(meQuery);
    
      useEffect(() => {
        if (me) analytics.identify(me.id);
      }, [me]);
    
      return null;
    }
    
    export function AnalyticsProvider({
      children,
    }: PropsWithChildren) {
      // 첫 렌더에서는 쿼리 캐시를 건드리지 않는다
      const isHydrated = useIsHydrated();
    
      return (
        <>
          {isHydrated && <AnalyticsIdentity />}
          {children}
        </>
      );
    }
    // app/layout.tsx (서버 컴포넌트)
    import type { ReactNode } from 'react';
    import {
      dehydrate,
      HydrationBoundary,
      QueryClient,
    } from '@tanstack/react-query';
    
    import { meQuery } from '../queries';
    
    export default async function AppLayout({
      children,
    }: {
      children: ReactNode;
    }) {
      const queryClient = new QueryClient();
      // dehydrate 전에 반드시 await한다
      await queryClient.prefetchQuery(meQuery);
    
      return (
        <HydrationBoundary state={dehydrate(queryClient)}>
          {children}
        </HydrationBoundary>
      );
    }

    analytics는 쓰는 분석 SDK 래퍼로 바꾸면 된다. 네 파일은 TypeScript strict로 typecheck 했고, 위 재현의 마지막 줄이 이 구조다.

    버린 방법도 있다. HydrationBoundary를 프로바이더 위로 올리는 건 dehydrate 상태를 하위 서버 레이아웃이 만들어서 불가능했다. 구독 컴포넌트를 {children} 뒤 형제로 두는 건 렌더 순서에 기대는데, 스트리밍 SSR에서 children이 suspend 하면 형제가 먼저 렌더 될 수 있다. getQueryData와 수동 캐시 구독은 동작하지만 useQuery의 재시도·에러 처리·meta 정책을 잃는다.

    에지 케이스

    바깥 HydrationBoundary도 조상이다. 처음 의심한 문제가 같은 구조였다. 상위 레이아웃이 쿼리를 await 없이 prefetch 했고 dehydrate 설정(shouldDehydrateQuery)은 pending 쿼리도 실었다. 바깥 boundary가 pending 엔트리를 먼저 hydrate 한다. 그러면 하위 레이아웃이 await 해 보낸 완료 데이터는 안쪽 boundary에서 이미 있는 쿼리가 되어 이펙트로 밀린다. 재현에서도 [pending]이 나왔다. dehydrate 전에 await 하고 prefetch는 그 쿼리를 쓰는 가장 바깥 레이아웃 한 곳에서만 하도록 정리했다. 레이아웃마다 새 QueryClient를 만들던 탓에 한 요청에서 백엔드를 두 번 부르던 중복도 함께 사라졌다.

    미룬 구독은 이펙트 용도에만 안전하다. 구독이 한 틱 늦게 시작하므로 analytics identify나 SDK boot처럼 렌더와 무관한 부수효과에만 맞다. 루트 UI가 첫 페인트에 쿼리 데이터를 필요로 하면 규칙을 다시 따져야 한다.

    문서화된 계약이 아니다. 라이브러리 내부 동작에 기댄 규칙이라 TanStack Query 메이저 업그레이드 때는 재현을 다시 돌려 봐야 한다.

    마무리

    prefetch 결과가 첫 페인트에 닿을지는 소비처가 아니라 QueryClientProvider와 HydrationBoundary 사이에서 정해진다. 그 사이의 컴포넌트가 같은 쿼리를 렌더 중에 구독하면 hydrate는 이펙트로 밀리고 SSR은 폴백을 그린다. 루트 프로바이더가 렌더 중에 쿼리 캐시를 건드리지 않게 하면 막을 수 있다.

    지금 QueryClientProvider 아래, 첫 HydrationBoundary 위에 있는 컴포넌트에서 useQuery를 검색해 보자.

    참고

    반응형

    댓글

Designed by Tistory.