Hydration 전략 - 🌲 Sonamu

Sonamu에서 서버 렌더링된 HTML을 클라이언트에서 인터랙티브하게 만드는 하이드레이션 전략을 알아봅니다.

Hydration 개요

TanStack Query

dehydrate/hydrate 자동 상태 복원

전체 문서 Hydration

document 레벨 완전한 SSR

Date 직렬화

dateReviver 자동 변환

선택적 비활성화

disableHydrate CSR 전환

Sonamu Hydration 프로세스

1. 서버: Dehydration

서버에서 Query상태를 직렬화합니다.

// entry-server.generated.tsx
import { dehydrate } from "@tanstack/react-query";

export async function render(url: string, preloadedData: PreloadedData[] = []) {
  const queryClient = new QueryClient();

  // 데이터 주입
  for (const { queryKey, data } of preloadedData) {
    queryClient.setQueryData(queryKey, data);
  }

  // Dehydrate: QueryClient 상태를 JSON으로 직렬화
  const dehydratedState = dehydrate(queryClient);

  const appHtml = renderToString(<RouterProvider router={router} />);

  return {
    html: appHtml,
    dehydratedState,  // 직렬화된 상태
  };
}

2. HTML에 데이터 주입

// sonamu/src/ssr/renderer.ts
const ssrDataScript = dehydratedState
  ? `<script>window.__SONAMU_SSR__ = ${JSON.stringify(dehydratedState).replace(/</g, "\\u003c")};</script>`
  : "";

// </body> 직전에 주입
const finalHtml = fullDocHtml.replace("</body>", `${ssrDataScript}\n${viteScripts}\n</body>`);

생성된 HTML:

<!DOCTYPE html>
<html>
  <head>
    ...
  </head>
  <body>
    <div id="root">
      <!-- 서버 렌더링된 HTML -->
      <div>Welcome, John</div>
    </div>

    <!-- SSR 데이터 -->
    <script>
      window.__SONAMU_SSR__ = {
        queries: [
          {
            queryKey: ["User", "getUser", "C", 123],
            queryHash: '["User","getUser","C",123]',
            state: {
              data: {
                user: {
                  id: 123,
                  username: "John",
                  createdAt: "2024-01-01T00:00:00.000Z",
                },
              },
              dataUpdateCount: 1,
              dataUpdatedAt: 1704067200000,
              status: "success",
            },
          },
        ],
      };
    </script>

    <!-- Vite 스크립트 -->
    <script type="module" src="/src/entry-client.tsx"></script>
  </body>
</html>

3. 클라이언트: Hydration

클라이언트에서 상태를 복원하고 React를 활성화합니다.

// entry-client.tsx
import { hydrate } from "@tanstack/react-query";
import { dateReviver } from "./services/sonamu.shared";

// 1. window.__SONAMU_SSR__에서 데이터 가져오기
const dehydratedState = window.__SONAMU_SSR__
  ? JSON.parse(JSON.stringify(window.__SONAMU_SSR__), dateReviver)
  : undefined;

// 2. QueryClient에 hydrate
if (dehydratedState) {
  hydrate(queryClient, dehydratedState);
}

// 3. React Hydration
if (document.documentElement.innerHTML && dehydratedState) {
  // SSR 페이지 - Hydration
  ReactDOM.hydrateRoot(document, <RouterProvider router={router} />);
} else {
  // Pure CSR 페이지 - 새로 렌더링
  ReactDOM.createRoot(document).render(<RouterProvider router={router} />);
}

Date 직렬화 처리

문제: Date 객체는 JSON.stringify로 문자열이 됨

const user = {
  id: 123,
  username: "John",
  createdAt: new Date("2024-01-01"), // Date 객체
};

// 서버에서 직렬화
JSON.stringify(user);
// '{"id":123,"username":"John","createdAt":"2024-01-01T00:00:00.000Z"}'
//                                          ↑ 문자열!

// 클라이언트에서 역직렬화
JSON.parse(json);
// { id: 123, username: "John", createdAt: "2024-01-01T00:00:00.000Z" }
//                                          ↑ 여전히 문자열!

해결: dateReviver

Sonamu는 자동으로 ISO 날짜 문자열을 Date 객체로 변환합니다.

// services/sonamu.shared.ts
export function dateReviver(_key: string, value: unknown): unknown {
  if (typeof value === "string") {
    // ISO 8601 날짜 문자열 패턴
    const isoDatePattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/;
    if (isoDatePattern.test(value)) {
      return new Date(value); // Date 객체로 변환
    }
  }
  return value;
}

// entry-client.tsx
const dehydratedState = window.__SONAMU_SSR__
  ? JSON.parse(JSON.stringify(window.__SONAMU_SSR__), dateReviver)
  : undefined;

// ✅ createdAt이 Date 객체로 복원됨!

Hydration Mismatch 방지

문제: 서버와 클라이언트의 HTML이 다르면 에러

// ❌ Hydration Mismatch 발생
function Clock() {
  const [time, setTime] = useState(new Date());
  // 서버와 클라이언트의 시간이 다름!

  return <div>{time.toLocaleTimeString()}</div>;
}

에러 메시지:

Warning: Text content did not match. Server: "10:30:45" Client: "10:30:47"

해결 1: useEffect 사용

// ✅ 클라이언트에서만 실행
function Clock() {
  const [time, setTime] = useState<Date | null>(null);

  useEffect(() => {
    setTime(new Date());
    const interval = setInterval(() => {
      setTime(new Date());
    }, 1000);
    return () => clearInterval(interval);
  }, []);

  if (!time) return <div>--:--:--</div>;  // 서버 렌더링
  return <div>{time.toLocaleTimeString()}</div>;  // 클라이언트만
}

해결 2: suppressHydrationWarning

의도적으로 서버/클라이언트가 다른 경우 사용합니다.

function RandomQuote() {
  const [quote] = useState(() => getRandomQuote());

  return (
    <div suppressHydrationWarning>
      {quote}  {/* 서버와 클라이언트가 다를 수 있음 */}
    </div>
  );
}

disableHydrate 옵션

Hydration을 비활성화하고 CSR로 전환

// api/src/application/sonamu.ts
registerSSR({
  path: "/admin/realtime-dashboard",
  preload: (params) => [
    /* ... */
  ],
  disableHydrate: true, // Hydration 비활성화
});

작동 방식:

// entry-client.tsx
const ssrConfig = window.__SONAMU_SSR_CONFIG__;

if (ssrConfig?.disableHydrate) {
  // Hydration 대신 새로 렌더링
  console.log("[Sonamu] Hydration disabled, rendering as CSR");
  ReactDOM.createRoot(document).render(<RouterProvider router={router} />);
} else {
  // 정상 Hydration
  ReactDOM.hydrateRoot(document, <RouterProvider router={router} />);
}

사용 사례:

실시간 데이터가 중요한 경우 (대시보드, 채팅 등)
서버/클라이언트 렌더링 결과가 의도적으로 다른 경우
Hydration mismatch 해결이 어려운 경우

전체 문서 Hydration

Sonamu는 document 전체를 hydrate합니다 (div#root가 아님).

// ❌ 일반적인 React 앱 (div#root만)
ReactDOM.hydrateRoot(
  document.getElementById("root"),
  <App />
);

// ✅ Sonamu (document 전체)
ReactDOM.hydrateRoot(
  document,
  <RouterProvider router={router} />
);

이유:

TanStack Router가 <html>, <head> 태그까지 관리
<HeadContent />, <Scripts /> 컴포넌트가 head/body 수정
SEO 메타 태그를 동적으로 변경 가능

// web/src/routes/__root.tsx
export const Route = createRootRouteWithContext<RouterContext>()({
  head: () => ({
    meta: [
      { charSet: "utf-8" },
      { title: "My App" },
    ],
  }),
  component: RootComponent,
});

function RootComponent() {
  return (
    <html lang="ko">
      <head>
        <HeadContent />  {/* head 태그 동적 생성 */}
      </head>
      <body>
        <div id="root">
          <Outlet />
        </div>
        <Scripts />  {/* script 태그 동적 생성 */}
      </body>
    </html>
  );
}

Suspense와 Hydration

서버에서 Suspense fallback을 렌더링하고 클라이언트에서 실제 컨텐츠를 로드할 수 있습니다.

// entry-server.generated.tsx
const appHtml = renderToString(
  <Suspense fallback={null}>  {/* Hydration mismatch 방지 */}
    <RouterProvider router={router} />
  </Suspense>,
);

fallback=을 사용하는 이유:

SSR에서는 모든 데이터가 이미 로드되어 있음
fallback이 보이지 않음
Hydration mismatch 방지

QueryClient 설정

서버 설정

// entry-server.generated.tsx
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5000, // 5초
      retry: false, // 서버에서는 재시도 안 함
    },
  },
});

클라이언트 설정

// entry-client.tsx
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5000, // 5초
      retry: false, // 재시도 안 함
      refetchOnMount: true, // 마운트 시 재검증
    },
  },
});

주의: 서버와 클라이언트의 staleTime을 동일하게 설정하는 것이 좋습니다.

Router Context

QueryClient를 Router Context로 전달합니다.

// web/src/routes/__root.tsx
export interface RouterContext {
  queryClient: QueryClient;
}

export const Route = createRootRouteWithContext<RouterContext>()({
  component: RootComponent,
});

function RootComponent() {
  const { queryClient } = Route.useRouteContext();

  return (
    <html>
      <body>
        <QueryClientProvider client={queryClient}>
          <Outlet />
        </QueryClientProvider>
      </body>
    </html>
  );
}

// entry-server.generated.tsx & entry-client.tsx
const router = createRouter({
  routeTree,
  context: { queryClient }, // Context로 전달
  defaultPreload: "intent",
});

디버깅

Hydration 확인

// entry-client.tsx
if (document.documentElement.innerHTML && dehydratedState) {
  console.log("[Sonamu] Hydrating with SSR data");
  console.log("Queries:", Object.keys(dehydratedState.queries || {}));
  ReactDOM.hydrateRoot(document, <RouterProvider router={router} />);
} else {
  console.log("[Sonamu] Rendering as CSR (no SSR data)");
  ReactDOM.createRoot(document).render(<RouterProvider router={router} />);
}

QueryClient 상태 확인

// Chrome Extension 지원
window.__TANSTACK_QUERY_CLIENT__ = queryClient;

// 콘솔에서 확인
window.__TANSTACK_QUERY_CLIENT__.getQueryCache().getAll();

주의사항

Hydration 사용 시 주의사항: 1. 서버/클라이언트 HTML 일치: Hydration mismatch 방지 2. window 객체 주의: 서버에서는 window가 없습니다 3. Date 객체: dateReviver가 자동 처리하지만 확인 필요 4. QueryClient 설정 동일: 서버와 클라이언트의 staleTime 일치 5. disableHydrate 최소화: 특별한 경우에만 사용

다음 단계

SSR 설정

SSR 기본 구조

데이터 프리로딩

registerSSR 사용법

캐시 제어

TanStack Query 캐싱

TanStack Query 공식 문서

Query 상세 가이드

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​Hydration 개요

TanStack Query

전체 문서 Hydration

Date 직렬화

선택적 비활성화

​Sonamu Hydration 프로세스

​1. 서버: Dehydration

​2. HTML에 데이터 주입

​3. 클라이언트: Hydration

​Date 직렬화 처리

​문제: Date 객체는 JSON.stringify로 문자열이 됨

​해결: dateReviver

​Hydration Mismatch 방지

​문제: 서버와 클라이언트의 HTML이 다르면 에러

​해결 1: useEffect 사용

​해결 2: suppressHydrationWarning

​disableHydrate 옵션

​Hydration을 비활성화하고 CSR로 전환

​전체 문서 Hydration

​Suspense와 Hydration

​QueryClient 설정

​서버 설정

​클라이언트 설정

​Router Context

​디버깅

​Hydration 확인

​QueryClient 상태 확인

​주의사항

​다음 단계

SSR 설정

데이터 프리로딩

캐시 제어

TanStack Query 공식 문서

Hydration 개요

Sonamu Hydration 프로세스

1. 서버: Dehydration

2. HTML에 데이터 주입

3. 클라이언트: Hydration

Date 직렬화 처리

문제: Date 객체는 JSON.stringify로 문자열이 됨

해결: dateReviver

Hydration Mismatch 방지

문제: 서버와 클라이언트의 HTML이 다르면 에러

해결 1: useEffect 사용

해결 2: suppressHydrationWarning

disableHydrate 옵션

Hydration을 비활성화하고 CSR로 전환

전체 문서 Hydration

Suspense와 Hydration

QueryClient 설정

서버 설정

클라이언트 설정

Router Context

디버깅

Hydration 확인

QueryClient 상태 확인

주의사항

다음 단계