Querying Singleton Pages
Singleton pages represent fixed structural models (such as Home, About, Pricing, or Legal) that map directly to a unique slug with zero schema migrations.
“The SDK resolves singleton documents through a 4-tier cascade: Memory → LocalStorage → Local .nx Binary → Remote Edge Gateway.”
The getPage() Method
The primary method for querying singleton content is nexus.getPage<T>(slug, options). When used inside Next.js Server Components, it automatically injects Next.js Data Cache tags (nexus_project_[id] and content_[slug]) so pages benefit from instantaneous ISR revalidation.
| 1 | import { nexus } from "@nexushub/client"; |
| 2 | import { NexusRichText, NexusImage } from "@nexushub/client/react"; |
| 3 | import type { HomePage } from "@/types/nexus"; |
| 4 | |
| 5 | export default async function Home() { |
| 6 | // 1. Fetch singleton with strong TypeScript autocomplete |
| 7 | const page = await nexus.getPage<HomePage>("home"); |
| 8 | |
| 9 | return ( |
| 10 | <main className="max-w-4xl mx-auto py-12 px-4"> |
| 11 | <h1 className="text-4xl font-extrabold">{page.hero_title}</h1> |
| 12 | <NexusImage value={page.hero_image} className="w-full h-80 my-6 rounded-2xl object-cover" /> |
| 13 | <NexusRichText value={page.body_content} /> |
| 14 | </main> |
| 15 | ); |
| 16 | } |
4-Layer Resolution Cascade
Every call to getPage() traverses four sequential layers before making a network request:
In-Memory LRU Cache
Checks JS heap for unexpired content. Resolves in 0.1ms without touching network or disk.
LocalStorage Vault
If cacheStrategy='localStorage', reads persistent client storage across tab refreshes.
Local .nx Binary
When NODE_ENV=development, reads .nexus/local/pages/[slug].nx offline with zero network calls.
Edge API Gateway
Fetches live content from Cloudflare CDN with exponential backoff and circuit-breaker protection.
Query Options Reference
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| revalidate | number | false | Optional | Time in seconds before Next.js revalidates the cache. Passing 0 forces a network-fresh fetch. Default: Inherits config.revalidateTime (false) |
| tags | string[] | Optional | Additional cache tags attached to Next.js fetch options for custom on-demand purge grouping. Default: [] |
| forceRefresh | boolean | Optional | Bypasses all in-memory and local disk caches, forcing an immediate outbound network request. Default: false |
| includeMetadata | boolean | Optional | Returns the full CacheEntry<T> envelope containing { data, metadata: { timestamp, etag, expiresAt } }. Default: false |
Server vs. Client Execution
GN-Apex handles the boundary between Node.js / Cloudflare Workers and client webviews transparently:
- Server-Side (RSC / SSR): The SDK injects
next: { tags, revalidate }and reads.nxlocal files via Nodefs. - Client-Side (Browser): The SDK gracefully swaps file system dependencies for browser-safe memory or LocalStorage implementations via package bundler exports.