NexusHydrationBoundary & withNexusHydrationBoundary

These are server-only APIs used to collect data fetched by nexus during a server render and serialize it for the client. This is the mechanism that powers automatic client-side hydration.

Core Concept: Server-to-Client Hydration

During a React Server Component (RSC) render, any calls to nexus are tracked. When you wrap a part of your component tree with one of these APIs, it acts as a boundary. At the end of the server render, the boundary collects all tracked nexus results from within its subtree and serializes them into a compact payload. This payload is sent to the client, where NexusRuntime uses it to populate the client-side cache.

NexusHydrationBoundary (Component)

This is a Server Component that you use to wrap a layout or a part of a page.

Import

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

When to Use

Use the component when you have a segment layout (layout.tsx) and want to enable hydration for all child pages within that segment. This is the most common and recommended approach.

Usage

Wrap the children of your layout component.

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

withNexusHydrationBoundary (HOC)

This is a Higher-Order Component (HOC) that you use to wrap a page component.

Import

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

When to Use

Use the HOC when you only need hydration for a single page within a segment and creating a separate layout.tsx file would be unnecessary boilerplate.

Usage

Export your page component wrapped in the HOC.

// app/dashboard/page.tsx
import { withNexusHydrationBoundary, nexus } from 'next-nexus/server';
 
async function DashboardPage() {
  // ... server logic with nexus(...)
  return <div>Dashboard</div>;
}
 
export default withNexusHydrationBoundary(DashboardPage);

Decision Guide

• Multiple pages in a segment need hydration → Use the NexusHydrationBoundary component in a shared layout.tsx.
• A single page in a segment needs hydration → Use the withNexusHydrationBoundary HOC on your page.tsx.
• Important: Do not apply both to the same rendered path, as this can cause unexpected behavior. Choose one method per segment.

See also

• NexusRuntime
• nexus