`NexusRuntime`

NexusRuntime is a client-only component that is essential for the client-side functionality of next-nexus. It should be placed once in your root layout.

Core Concepts

Client-Side Cache Initialization

The component initializes the in-memory LRU cache used by all client-side hooks (useNexusQuery, useNexusMutation, etc.). This cache is what makes client-side state management and revalidation possible.

Hydration Receiver

NexusRuntime is responsible for receiving the hydration payload serialized by NexusHydrationBoundary. When the client-side application mounts, this component applies the payload, “hydrating” the client cache with the data that was already fetched on the server. This ensures a seamless transition from server-rendered content to an interactive client-side application without refetching data.

RSC Request Integration

During client-side navigations (RSC requests), NexusRuntime automatically intercepts fetch calls to add cookies containing metadata about the client’s cache state (__NEXUS_CLIENT_CACHE__). This allows the server to make intelligent decisions, such as:

Skipping hydration for data the client already has (based on ETag).
Instructing the client to extend the TTL for not-modified cache entries. This process is key to features like Rendering Delegation with NexusRenderer.

Import


import { NexusRuntime } from 'next-nexus/client';

Usage

Insert NexusRuntime once in your root layout (app/layout.tsx), just before the closing </body> tag.


// app/layout.tsx
import { NexusRuntime } from 'next-nexus/client';
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <NexusRuntime />
      </body>
    </html>
  );
}

Important: Do not add this component to nested layouts or any other component. It must be installed exactly once, globally.

Props

maxSize?: number (default: 200) — The maximum number of entries for the client-side LRU cache.

See also