시작하기

두 단계를 따라 next-nexus를 활성화하고, 마지막 체크리스트로 올바르게 설정했는지 검증해 보세요.

1) 전역 클라이언트 런타임 설치 (최초 1회)

루트 레이아웃에 NexusRuntime 컴포넌트를 한 번만 추가합니다. 이 컴포넌트는 클라이언트 캐시를 초기화하고 RSC 요청 시 클라이언트 캐시 메타데이터를 전송합니다.


// app/layout.tsx
import { NexusRuntime } from "next-nexus/client";
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ko">
      <body>
        {children}
        {/* 전역으로 한 번만 설치해야 합니다. 중첩된 레이아웃에 추가하지 마세요. */}
        <NexusRuntime />
      </body>
    </html>
  );
}

Notes

전역으로 딱 한 번만 설치해야 합니다. 중복 설치 시 불필요한 작업이 수행될 수 있습니다.
페이지 트리 마운트가 끝난 후 런타임이 초기화되도록 </body> 태그 직전에 위치시키는 것을 권장합니다.

2) 데이터 페칭 세그먼트에 하이드레이션 활성화

데이터를 페칭하는 세그먼트를 하이드레이션 경계로 감싸야 합니다. 세그먼트 레이아웃 또는 페이지 레벨 HOC를 사용할 수 있습니다.

방법 A — 세그먼트 레이아웃 경계 데이터를 가져오는 페이지가 세그먼트 내에 여러 개 있을 때 권장하는 방식입니다.


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

방법 B — 페이지 레벨 HOC 해당 세그먼트에 별도의 레이아웃 파일이 필요 없을 때 사용합니다.


// app/(shop)/products/page.tsx
import { withNexusHydrationBoundary, nexus } from "next-nexus/server";
import { productDefinition } from "@/api/productDefinition";
 
async function ProductsPage() {
  const { data: products, headers } = await nexus(productDefinition.list);
  const total = headers.get("x-total-count");
  return (
    <div>
      <h1>상품 목록 ({total ?? "n/a"})</h1>
      <ul>
        {products?.map((p) => (
          <li key={p.id}>{p.name}</li>
        ))}
      </ul>
    </div>
  );
}
 
export default withNexusHydrationBoundary(ProductsPage);

어떤 방법을 선택할까요?

동일 세그먼트 내 여러 페이지에서 데이터를 가져온다면 레이아웃 경계를 사용하세요.
단일 페이지만 데이터를 가져오거나, 불필요한 레이아웃 파일을 만들고 싶지 않다면 페이지 HOC가 좋은 선택입니다.

설정 검증 체크리스트

루트 레이아웃에 <NexusRuntime />이 정확히 한 번만 설치되었나요?
하나의 페이지 경로에는 레이아웃 경계 또는 페이지 HOC 중 하나만 적용되었나요? (중복 적용 금지)
서버 코드는 "next-nexus/server", 클라이언트 코드는 "next-nexus/client"에서 올바르게 가져왔나요?
모든 definition은 공통 팩토리(createNexusDefinition)를 통해 생성하고, 제네릭으로 응답 타입을 명시했나요?

다음 단계

definition 작성하기: Definitions
서버에서 데이터 가져오기: nexus
클라이언트에서 데이터 조회하기: useNexusQuery