Skip to Content
Getting Started

Getting Started

Follow two steps to enable next-nexus end-to-end, then verify your setup with the checklist.

1) Install the global client runtime (once)

Add the NexusRuntime component once in your root layout. This initializes the client cache and sends client cache metadata with RSC requests.

// app/layout.tsx
import { NexusRuntime } from "next-nexus/client";
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        {/* Install once globally. Do not put this in nested layouts. */}
        <NexusRuntime />
      </body>
    </html>
  );
}

Notes

  • Install exactly once globally. Multiple installations can cause duplicate work.
  • Keep it near the closing </body> tag so it mounts after your page tree.

2) Enable hydration in data-fetching segments

Wrap segments that fetch data with a hydration boundary. This can be done at the segment layout level or with a page-level HOC.

Option A — Segment layout boundary This is recommended for segments with multiple pages that fetch data.

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

Option B — Page-level HOC Use this when the segment doesn’t need its own layout file.

// 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>Products ({total ?? "n/a"})</h1>
      <ul>
        {products?.map((p) => (
          <li key={p.id}>{p.name}</li>
        ))}
      </ul>
    </div>
  );
}
 
export default withNexusHydrationBoundary(ProductsPage);

Decision guide

  • Use a layout boundary when several sibling pages under the same segment fetch data.
  • Use the page HOC when only a single page fetches data and a new layout file would be boilerplate.

Validation checklist

  • The root layout contains exactly one <NexusRuntime />.
  • Exactly one hydration boundary applies to a given rendered page (either the segment layout OR the page HOC, not both).
  • Server code is imported from "next-nexus/server", and client code is imported from "next-nexus/client".
  • All definition objects are created via a shared factory (createNexusDefinition) and include explicit generic response types.

Next steps

Last updated on
IntroductionLifecycle