NexusHydrationBoundary & withNexusHydrationBoundary

이 API들은 서버 렌더링 중 nexus로 가져온 데이터를 수집하여 클라이언트로 전달하기 위해 직렬화하는 서버 전용 API입니다. 이 메커니즘을 통해 클라이언트 사이드 하이드레이션이 자동으로 이루어집니다.

핵심 개념: 서버-클라이언트 하이드레이션

React 서버 컴포넌트(RSC) 렌더링 중에 발생하는 모든 nexus 호출은 추적됩니다. 이 API들 중 하나로 컴포넌트 트리의 일부를 감싸면, 그 경계선 역할을 합니다. 서버 렌더링이 끝나면, 이 경계는 하위 트리 내에서 추적된 모든 nexus 결과를 수집하여 간결한 페이로드로 직렬화합니다. 이 페이로드는 클라이언트로 전송되며, NexusRuntime이 이를 사용하여 클라이언트 캐시를 채웁니다.

NexusHydrationBoundary (컴포넌트)

레이아웃이나 페이지의 일부를 감싸는 데 사용하는 서버 컴포넌트입니다.

Import

import { NexusHydrationBoundary } from 'next-nexus/server';

언제 사용하나요?

세그먼트 레이아웃(layout.tsx)이 있고 해당 세그먼트 내의 모든 자식 페이지에 대해 하이드레이션을 활성화하고 싶을 때 사용합니다. 가장 일반적이고 권장되는 접근 방식입니다.

사용법

레이아웃 컴포넌트의 children을 감싸줍니다.

// app/products/layout.tsx
import { NexusHydrationBoundary } from 'next-nexus/server';
 
export default function ProductsLayout({ children }: { children: React.ReactNode }) {
  return <NexusHydrationBoundary>{children}</NexusHydrationBoundary>;
}

withNexusHydrationBoundary (HOC)

페이지 컴포넌트를 감싸는 데 사용하는 고차 컴포넌트(Higher-Order Component)입니다.

Import

import { withNexusHydrationBoundary } from 'next-nexus/server';

언제 사용하나요?

세그먼트 내의 단일 페이지에만 하이드레이션이 필요하고, 별도의 layout.tsx 파일을 만드는 것이 불필요한 보일러플레이트일 때 사용합니다.

사용법

HOC로 감싼 페이지 컴포넌트를 export합니다.

// app/dashboard/page.tsx
import { withNexusHydrationBoundary, nexus } from 'next-nexus/server';
 
async function DashboardPage() {
  // ... nexus(...)를 사용한 서버 로직
  return <div>대시보드</div>;
}
 
export default withNexusHydrationBoundary(DashboardPage);

선택 가이드

• 세그먼트 내 여러 페이지에 하이드레이션이 필요한 경우 → 공통 layout.tsx에서 NexusHydrationBoundary 컴포넌트를 사용하세요.
• 세그먼트 내 단일 페이지에만 하이드레이션이 필요한 경우 → page.tsx에서 withNexusHydrationBoundary HOC를 사용하세요.
• 중요: 동일한 렌더링 경로에 두 가지 방법을 모두 적용하지 마세요. 예기치 않은 동작을 유발할 수 있습니다. 세그먼트당 하나의 방법만 선택하세요.

함께 보기

• NexusRuntime
• nexus