Lifecycle

A quick mental model of how data flows through next‑nexus.

Prerequisites: Use factory definitions only, set up NexusRuntime in the root layout, and wrap data-fetching segments with NexusHydrationBoundary (or export pages with withNexusHydrationBoundary). See /en/getting-started and /en/api/definitions for details.

At a glance

1. Define endpoints with factories (the cache key comes from the definition).
2. The server (RSC) renders and calls nexus(...) where needed; response headers and payload are collected.
3. Hydration: The collected entries are serialized to the client via NexusHydrationBoundary.
4. The client mounts; NexusRuntime hydrates the cache with the restored entries.
5. Reading data: On the server use nexus(...); on the client use useNexusQuery.
6. Writing data: Use useNexusMutation, useNexusAction, or useNexusFormAction, then revalidate via tags.
7. cache, revalidate, and tags map directly to the Next.js request cache and ISR.
8. Errors are normalized; detect them with isNexusError.
9. Debugging logs can print request/cache events in dev mode.

One diagram

Route/navigation
   ↓
Server RSC render ──▶ nexus(def, opts) ──▶ collect {data, etag, headers}
   ↓                                     \
Hydration payload ◀─────────────────────── restore on client
   ↓
Client render ──▶ useNexusQuery(...) ──▶ cache read/write, optional revalidate/tag
   ↓
Mutations/Actions ──▶ revalidate tags ──▶ re-fetch where subscribed

What runs where

• Server: Reads inbound headers, performs nexus(...) in RSC, collects hydration entries.
• Client: Restores hydration data, runs hooks, optionally accesses cached response headers.

Next

• Start with Reading Data → /en/core-concepts/reading-data
• Then Writing Data → /en/core-concepts/writing-data