노트

서버 렌더에서 훅이 하는 일

Hooks During Server Rendering

프런트엔드#react#performance · 연결된 개념 9개

쉽게 말하면

서버 렌더에서 훅은 리허설 무대에 선 배우 같아요. 대사인 계산은 다 하지만 조명과 소품을 쓰는 진짜 동작인 Effect는 건너뛰어서, 렌더 중에 값을 계산하는 훅만 일해요.

비유가 깨지는 곳 리허설이라고 흔적이 안 남는 건 아니에요. 렌더 경로의 부수 효과는 요청마다 쌓이고, useQuery는 서버에서도 쿼리를 등록해서 유한한 gcTime을 주면 타이머가 그 요청의 캐시를 붙잡아 메모리가 늘어요.

서버 렌더(Server-Side Rendering, SSR)에서도 컴포넌트 함수는 실제로 호출되고, 그 안의 훅도 호출은 된다. 다만 서버에는 커밋(DOM 반영)이 없어서, 렌더 중 동기적으로 값을 계산하는 훅만 일하고 커밋 뒤에 도는 훅은 아무것도 하지 않는다. "이 훅은 클라이언트에서만 동작한다"는 말은 대개 "Effect 안의 일은 클라이언트에서만 일어난다"는 뜻이다.

훅서버에서
useState(초기화 함수)·useReducer초기화 함수까지 실행해 초기 state를 만든다
useMemo·useCallback·useRef·useContext그대로 실행
useSyncExternalStoresubscribe는 부르지 않고 getServerSnapshot()의 값만 쓴다
useEffect·useLayoutEffect·useInsertionEffect아무것도 하지 않음(no-op)
  • React 19.2의 서버 렌더러 소스에서 Effect 계열 훅은 빈 함수이고, useSyncExternalStore는 getServerSnapshot()을 반환할 뿐이다(2026 기준). 경고 없이 조용히 무시된다
  • getServerSnapshot을 빠뜨리면 서버에서 에러가 나고, 가장 가까운 Suspense 경계부터 클라이언트 렌더로 넘어간다(CSR bailout). 서버에서 의미 있는 값이 없을 때 일부러 이렇게 클라이언트 전용으로 미루기도 한다(useSyncExternalStore)
  • getServerSnapshot은 하이드레이션 때도 쓰인다. 서버와 클라이언트가 같은 값을 내야 하이드레이션 불일치가 나지 않는다

렌더 중 부수 효과는 서버에서 쌓인다

브라우저에서는 탭을 닫으면 끝나지만, 서버 프로세스는 수많은 요청을 오래 처리한다. 렌더 경로(초기화 함수, useMemo, 컴포넌트 본문)에서 생긴 부수 효과는 Effect처럼 건너뛰어지지 않으니 요청마다 실행되고 정리되지 않으면 누적된다. 렌더를 순수하게 두라는 React의 규칙과 렌더 순수성가 서버에서는 메모리 문제로 돌아온다.

TanStack Query의 useQuery가 좋은 예다. 서버에서도 useState 초기화 함수로 옵저버를 만들고, 그 과정에서 쿼리를 캐시에 등록한다. 데이터 요청(fetch)과 구독은 Effect·subscribe 쪽이라 서버에서 일어나지 않지만, 쿼리 등록과 GC 타이머 예약은 동기 코드라 서버에서도 일어난다.

useQuery → useState(() => new QueryObserver) → 캐시에 Query 등록 → scheduleGc()
  gcTime이 유한하면 setTimeout(gcTime) 예약
  → 타이머가 Query를, Query가 그 요청의 QueryCache 전체를 붙잡는다

TanStack Query v5 공식 SSR 가이드와 소스로 확인한 점(2026 기준, v5.104).

  • 서버의 gcTime 기본값은 Infinity(브라우저는 5분)다. Infinity면 타이머를 아예 만들지 않아서, 요청이 끝나면 그 요청의 캐시가 통째로 가비지 컬렉션(Garbage Collection) 대상이 된다
  • 훅이나 defaultOptions에서 유한한 gcTime을 직접 주면 서버에서도 그 시간만큼 타이머가 살아 있다. 24시간처럼 길게 주면 요청마다 만든 캐시가 그만큼 메모리에 남고, 타이머 하나가 같은 캐시의 다른 쿼리까지 함께 붙잡는다. 가이드는 이 경우 "캐시를 직접 일찍 비울 책임이 있다"고 한다(예: dehydrate 뒤 queryClient.clear())
  • 서버에서만 gcTime: 0으로 분기하는 방법도 쓰이지만, 가이드는 0이 하이드레이션 에러를 낼 수 있으니 피하라고 한다. 서버에서는 유한값으로 덮어쓰지 않는 쪽(기본값 Infinity 유지)이 먼저다
  • 반대로 QueryClient를 모듈 최상위에서 하나만 만들면 메모리 문제가 아니라 모든 사용자가 같은 캐시를 공유해 데이터가 다른 사용자에게 섞이는 문제가 된다. 요청마다(컴포넌트 안 state로) 만든다
  • SSR에서는 클라이언트가 받자마자 다시 요청하지 않도록 staleTime을 0보다 크게 두라고 권한다(staleTime과 gcTime)

서버 메모리가 계단처럼 오르기만 하면 힙 스냅샷에서 무엇이 붙잡고 있는지(retainer)를 따라가 GC 루트(활성 타이머, 전역 변수, 모듈 스코프 캐시)를 찾는다(크롬 개발자 도구 팁).

출처: React - useEffect: Caveats · React - useSyncExternalStore: Adding support for server rendering · TanStack Query - Server Rendering & Hydration

연결된 개념

이 노트를 가리키는 문서

뜻이 가까운 노트

  • 부수 효과와 Effect

    부수 효과(Side Effect)는 함수가 값을 계산해 돌려주는 본업 외에 바깥 세계를 건드리는 모든 동작이다. React의 Effect(useEffect로 감싼 코드)는 그중에서도 렌더가 끝난 뒤 외부 시스템과 맞추려고 실행하는 부수 효과만 가리키는 좁은 이름이다. 즉 Effect는 부수 효과의 부분집합이다.

  • Effect가 필요 없는 경우

    Effect는 외부 시스템과 동기화할 때 쓰는 탈출구(Escape Hatch)다. 렌더 중에 계산할 수 있는 값이나 사용자 이벤트 처리에 Effect를 쓰면 렌더가 한 번 더 일어나고 흐름이 꼬인다. React 공식 문서가 이런 경우를 따로 정리해 두었다.

  • 서버 함수와 서버 액션

    서버 함수(Server Function)는 'use server'로 표시해 서버에서만 실행되지만 클라이언트에서 네트워크 요청으로 호출할 수 있는 async 함수다. 그중 폼 제출이나 데이터 변경처럼 action 맥락(form action, transition)에서 쓰이는 것을 서버 액션(Server Action)이라 부른다. 서버 액션은 서버 함수의 부분집합이다.

  • use()로 Promise 읽기

    use()는 렌더 중에 Promise나 Context 같은 리소스의 값을 읽는 React 19 API(Application Programming Interface)다. Promise가 아직 pending이면 컴포넌트가 suspend되어 가장 가까운 suspense의 fallback이 보이고, 끝나면 그 값으로 다시 렌더된다. reject되면 가장 가까운 에러 경계(Error Boundary)로 던져진다.

  • React.cache

    cache(fn)은 서버 컴포넌트(Server Component)용 React API(Application Programming Interface)로, 함수 결과를 한 번의 서버 요청(렌더) 동안만 기억한다. 같은 요청 안에서 같은 인자로 여러 번 불러도 실제 실행은 한 번이다. React 19 정식 API이며 서버 컴포넌트에서만 쓴다.

보기 옵션