Escape the binary “all-or-nothing” route model. Dinou decomposes caching and rendering across three independent, orthogonal axes—Horizontal (layout_functions.ts), Vertical (<DinouCacheSlot>), and Temporal (Partial Prerendering / PPR)—which work standalone (3), in all 3 pairwise combinations, or in full Triple Synergy (1) on the same route, yielding 7 distinct architectural combinations (2³ − 1 = 7).
Traditional web frameworks treat a URL route as a single monolithic unit: either the entire page is static, or a single dynamic query forces the entire tree (layouts, sibling widgets, and page body) to re-render on every request. Dinou replaces that limitation with three orthogonal segmentation layers:
layout.tsx) from child pages (page.tsx) via layout_functions.ts, giving each segment its own independent data fetching, cache TTL, and surgical revalidation.refreshSlot).<Suspense> holes in parallel.Because the three axes are 100% orthogonal, you can adopt them incrementally—using a single axis, any pairwise combination, or all three together:
layout_functions.ts & page_functions.ts<DinouCacheSlot> Micro-ISR<Suspense> Holes)<DinouCacheSlot><DinouCacheSlot> + PPR<DinouCacheSlot>slayout_functions.ts)Along the horizontal axis, Dinou decouples the caching, data-fetching, and rendering lifecycle of every nested layout.tsx (and parallel @slot routes) from its child page.tsx via companion layout_functions.ts files.
Every layout_functions.ts file supports the exact same lifecycle functions as page_functions.ts (getProps, revalidate, getCacheTags, validateParams, getStaticPaths, allowISG, and ppr), allowing Dinou to cache and manage layouts and pages independently:
layout_functions.ts): Controls data fetching, cache duration, and invalidation tags exclusively for layout.tsx (and its parallel @slot routes).page_functions.ts): Controls data fetching, cache duration, and invalidation tags exclusively for page.tsx, without affecting or re-running the parent layout.allowISG & validateParams): On nested dynamic routes, each segment evaluates only the dynamic parameters accumulated up to that segment along the active layout chain—so a parent dynamic layout locked with allowISG = false never blocks valid child dynamic pages from generating new parameters on-demand via allowISG = true, and parent validateParams never sees deeper child parameters.Layout has revalidate = false (cached forever); child page has revalidate = 0 (live SSR). On every request or SPA navigation, the layout is served from cache in ~1.20ms without re-executing layout.tsx, while page.tsx renders live.
Layout has revalidate = 0 (evaluates per request); child page has revalidate = false. The heavy child page stays cached while the layout wrapper updates dynamically on every visit.
A workspace layout caches navigation for 1 hour (revalidate = 3600) while a child metrics page revalidates every 10 seconds (revalidate = 10), or vice versa, eliminating redundant database queries.
// src/dashboard/layout_functions.ts
import type { LayoutFunctions } from "./dinou";
// Parent layout caches independently for 1 hour (3,600s) with its own tag
export const revalidate: LayoutFunctions["revalidate"] = 3600;
export const getCacheTags: LayoutFunctions["getCacheTags"] = ["workspace-nav"];
export async function getProps() {
const workspaceNav = await db.workspaces.getNavigationTree();
return { workspaceNav };
}Because layouts and pages are cached independently, you can invalidate just the page (revalidatePage), just the layout (revalidateLayout), both at once (revalidatePath), or target either by tag (revalidateTag)—see Revalidation for full API signatures and propagation details:
// src/dashboard/actions.ts
"use server";
import {
revalidateLayout,
revalidatePage,
revalidatePath,
revalidateTag,
} from "dinou/server";
// 1. Revalidates ONLY /dashboard/layout.tsx (child pages are NOT re-executed)
export async function updateWorkspaceNav() {
await revalidateLayout("/dashboard"); // or await revalidateTag("workspace-nav")
}
// 2. Revalidates ONLY /dashboard/analytics/page.tsx (layout is NOT re-executed)
export async function updateAnalyticsPage() {
await revalidatePage("/dashboard/analytics");
}
// 3. Revalidates BOTH the layout and the page at /dashboard/analytics
export async function updateEverything() {
await revalidatePath("/dashboard/analytics");
}When you invalidate only a layout via await revalidateLayout("/dashboard") or await revalidateTag("workspace-nav") (or when a layout's clock TTL expires), Dinou avoids rebuilding your entire site at once:
/dashboard/layout.tsx without eagerly rebuilding nested sub-layouts or re-running any child page.tsx / page_functions.ts (all cached child pages remain 100% intact)./dashboard/settings/layout.tsx), Dinou does not rebuild it upfront when /dashboard is revalidated. Instead, the first time a visitor navigates to or requests /dashboard/settings, Dinou detects that the parent /dashboard layout is newer and lazily updates the nested sub-layout on demand so it wraps the fresh parent layout.F5): Likewise, when a visitor loads or hard-reloads (F5) any child page after its layout was updated, Dinou lazily combines the updated layout with the already-cached child page on the fly (without re-executing the child page.tsx). This guarantees zero React hydration mismatch without triggering a rebuild storm across all child pages.router.refresh)Horizontal Segmentation also extends to the browser. Because the client router manages the layout and the page as separate segments, you can navigate between pages or refresh the screen without re-fetching or losing state in your layout:
@slots, and the page once on the server and streams client hydration data inline inside the initial HTML response—requiring 0 extra network requests to hydrate and preventing hydration mismatches even with live timestamps or counters.<Link>): Navigating between pages that share a layout (e.g., /dashboard/overview → /dashboard/analytics) fetches only the new page. The layout makes 0 network requests and keeps 100% of its Client Component state (useState, open sidebars, scroll position, input text).<Link fresh>: Visited pages are cached in client memory so clicking back/forward is instant (0 network requests). Pass the fresh prop on <Link href="..." fresh> whenever you want a click to bypass the client cache and fetch fresh page data from the server.router.refresh() (Page Only): Re-fetches only the active page from the server while leaving the parent layout untouched (0 layout requests).router.refresh({ layout: true }) (Layout + Page): Re-fetches both the layout and the active page from the server (for example, after a Server Action updated the layout) and updates the screen in place without unmounting your Client Components or losing their interactive state (such as open menus, form inputs, or useState values)."use client";
import { Link, useRouter } from "dinou";
export function WorkspaceControls() {
const router = useRouter();
return (
<div className="flex gap-2">
{/* 1. Refreshes ONLY the current page (layout is not re-fetched) */}
<button onClick={() => router.refresh()}>
Refresh Page Only
</button>
{/* 2. Refreshes BOTH the layout and the page in place
without resetting interactive Client Component state */}
<button onClick={() => router.refresh({ layout: true })}>
Refresh Layout + Page
</button>
{/* 3. Forces a fresh server fetch on navigation */}
<Link href="/dashboard/analytics" fresh>
Fresh Analytics
</Link>
</div>
);
}<DinouCacheSlot>)While Horizontal Segmentation isolates route segments (layout.tsx vs. page.tsx), Vertical Segmentation isolates individual Server Component subtrees inside a layout or page. When a page contains an expensive database widget, developers in traditional frameworks are often forced to convert it into a Client Component with client-side fetching libraries, introducing bundle bloat, network waterfalls, and layout shifts.
Dinou solves this with <DinouCacheSlot> (imported from "dinou/server"). It keeps your widgets on the server as React Server Components (RSC) while giving each wrapped subtree its own independent server cache, expiration time (revalidate), and invalidation tags (tag / tags).
<DinouCacheSlot> Props Reference (import { DinouCacheSlot } from "dinou/server")Best practice: always assign a unique, descriptive id to each <DinouCacheSlot>, and add tag or tags whenever you want to invalidate it with revalidateTag() or group multiple slots together:
| Prop | Type | How It Works |
|---|---|---|
| id? | string | Unique identifier for this slot's cache entry on the server and for targeting it from the client via refreshSlot(id). Recommended on every <DinouCacheSlot> using a descriptive string (e.g., id="dashboard-analytics"—never reuse the same id across different slots). If omitted, Dinou falls back to tag || tags[0]. |
| tag? | string | Assigns a single cache tag to invalidate the slot on the server via revalidateTag(tag) (or refresh all slots sharing that tag in the browser via refreshSlot(tag)). If both tag and tags are provided, Dinou merges and deduplicates them (though preferring either tag for one or tags for multiple is cleanest). Note that id is also matched automatically by revalidateTag(id); if id is omitted, tag || tags[0] becomes the slot's id. |
| tags? | string[] | Array of cache tags when a slot needs multiple tags at once (for example, an individual tag plus a shared group tag: tags={["sales-chart", "billing-group"]}). If id is omitted, tags[0] is used as the slot's id. |
| revalidate? | number | false | Controls how long (in seconds) the rendered Server Component output stays fresh in the server cache:
|
| children | ReactNode | (() => ReactNode | Promise<ReactNode>) | The Server Component subtree to render and cache. You can pass standard JSX (an async or synchronous component such as <AsyncWidget /> or <SyncWidget />) or an inline async or synchronous function ({async () => { ... }} or {() => { ... }}) to compute or fetch data directly inline without creating a separate component. |
<DinouCacheSlot>id + Optional tag / tagsAlways give each slot a unique, descriptive id (e.g., <DinouCacheSlot id="analytics-widget">)—this alone caches the slot on the server, lets you refresh it from the client via refreshSlot("analytics-widget"), and lets you invalidate it on the server via revalidateTag("analytics-widget"). Add tag or tags whenever you want additional semantic or shared group tags to invalidate several widgets together (e.g., tags={["sales", "billing-group"]}).
/products/[slug])In dynamic routes like /products/[slug], every product URL renders the same page.tsx. Include the route parameter in the slot's ID and tags—such as id={`reviews-${params.slug}`} and tags={[`reviews-${params.slug}`, "all-reviews"]}—so each product caches its own slot separately while still allowing you to purge a single product or all products at once.
Outer → Inner Isolation)A slow-changing outer slot (e.g., a category tree with revalidate={3600}) can wrap a fast-changing inner slot (e.g., a flash-deals banner with revalidate={30}). When the inner slot expires or is invalidated, Dinou re-runs only the inner slot and plugs its fresh output into the already-cached outer slot without re-running the outer query.
Although <DinouCacheSlot> runs on the server, the UI inside it can render interactive "use client" components and pass "use server" functions as props. When refreshSlot() updates that slot in the browser, React updates the server props in place without unmounting those Client Components, preserving open dropdowns, typed text, and local useState values.
A frequent question is: Is <DinouCacheSlot> meant for dynamic or static pages? It functions as a universal caching primitive across both dynamic SSR and static/ISR routes:
The outer route is dynamic (reading session cookies, auth tokens, or revalidate = 0). Without a slot, every user request re-executes all expensive queries. With <DinouCacheSlot>, the personalized user greeting renders live, while the 2-second analytics calculation is served from server cache in ~2ms.
A product catalog page has a slow 24-hour page revalidation (revalidate = 86400). Inside it, a volatile inventory counter uses <DinouCacheSlot revalidate={60}>. The heavy outer page remains cached for 24h, while the volatile widget updates independently via background SWR.
The route runs in Live SSR mode (evaluating user cookies and personal widgets live). Heavy calculations are cached on the server, including multi-tag slots, inline async function children, and nested Outer → Inner slots:
// src/dashboard/page.tsx
import { Suspense } from "react";
import { DinouCacheSlot } from "dinou/server";
import { FastUserProfile, SlowAnalyticsWidget, FlashDealsBanner } from "./widgets";
import { AnalyticsSkeleton, CatalogSkeleton } from "./skeletons";
export default function DashboardPage() {
return (
<main className="grid grid-cols-1 md:grid-cols-2 gap-6 p-6">
{/* 1. Dynamic Component: Evaluated live on every request (reads session/cookies) */}
<FastUserProfile />
{/* 2. Smart Cache-Aware <Suspense> + <DinouCacheSlot>:
- 1st request (cold cache miss): streams <AnalyticsSkeleton /> immediately, then swaps in the widget
- 2nd+ requests (cache hit & background SWR): resolves from server slot cache (~1-2ms) without suspending (0 fallback flash)! */}
<Suspense fallback={<AnalyticsSkeleton />}>
<DinouCacheSlot id="analytics-widget" tags={["analytics", "dashboard-group"]} revalidate={300}>
<SlowAnalyticsWidget />
</DinouCacheSlot>
</Suspense>
{/* 3. Nested Slots (Outer 1h cache -> Inner 30s cache) + Inline async function child:
Wrapped in <Suspense> so cold cache misses never block TTFB on this Dynamic SSR page */}
<Suspense fallback={<CatalogSkeleton />}>
<DinouCacheSlot id="catalog-outer" tag="catalog-tree" revalidate={3600}>
{async () => {
const categories = await db.categories.getTree();
return (
<section>
<CategoryList items={categories} />
{/* Invalidating "flash-deals" re-renders ONLY this inner slot */}
<DinouCacheSlot id="flash-deals-banner" tag="flash-deals" revalidate={30}>
<FlashDealsBanner />
</DinouCacheSlot>
</section>
);
}}
</DinouCacheSlot>
</Suspense>
</main>
);
}The parent route has a slow revalidation of 24 hours (revalidate = 86400). Inside it, a volatile inventory counter revalidates vertically every 60 seconds (revalidate={60}) or on-demand when purchases occur:
import type { PageProps } from "./dinou";
import { DinouCacheSlot } from "dinou/server";
import { ProductHero, ProductDescription } from "./static-widgets";
import { LiveStockCounter } from "./stock-widgets";
export default function ProductDetailPage({ params }: PageProps) {
return (
<main className="container py-8 space-y-6">
{/* 1. Heavy Static Content: Cached for 24 hours */}
<ProductHero slug={params.slug} />
<ProductDescription slug={params.slug} />
{/* 2. Static Shell Micro-ISR Slot: Pre-rendered into initial HTML at build time,
and refreshed every 60s via non-blocking Background SWR (0ms TTFB) */}
<DinouCacheSlot
id={`stock-${params.slug}`}
tags={[`stock-${params.slug}`, "all-stock"]}
revalidate={60}
>
<LiveStockCounter slug={params.slug} />
</DinouCacheSlot>
</main>
);
}import type { PageFunctions } from "./dinou";
// Slow revalidation for outer page & descriptions (24 hours = 86,400s)
export const revalidate: PageFunctions["revalidate"] = 86400;<DinouCacheSlot> in <Suspense> vs. UnwrappedOn standalone non-PPR routes, whether you wrap <DinouCacheSlot> inside an outer <Suspense> depends on whether the page is Dynamic SSR or Static / ISR:
In Dynamic SSR pages (Pattern 1 above), wrap every top-level <DinouCacheSlot> in <Suspense fallback={...}> so a cold cache miss never blocks the page's TTFB: Dinou streams the fallback skeleton only on a cold cache miss (1st request or after revalidateTag), and once cached (including across expired TTLs via Background SWR), resolves the cached widget directly during the SSR pass (~1–2ms) without suspending (zero fallback flash).
In Static / ISR pages (Pattern 2 above), leave <DinouCacheSlot> outside <Suspense>. The widget is pre-rendered directly into the static HTML at build time (0ms TTFB) and refreshed in the background via SWR whenever its TTL expires. Even when invalidated on-demand via revalidateTag, it never blocks incoming requests: visitors always receive a cached response immediately—serving the previous cached version while revalidateTag is in progress, and the newly updated version as soon as it resolves.
💡 Combining <DinouCacheSlot> with Partial Prerendering (PPR)? See Section 6 (Vertical + Temporal) for how <Suspense> nesting controls Static Shell Slots vs. Cached Dynamic Holes.
refreshSlot), Tag Purging (revalidateTag) & Background SWRDinou provides surgical mechanisms to refresh or purge <DinouCacheSlot> instances without re-rendering the surrounding page:
refreshSlot)Any interactive Client Component (or client module) can trigger a surgical re-render of a specific slot (by id or tag) or all slots via wildcard "*" (updating both the slots currently mounted in the active page/layout and any slots cached in the client SPA session from previously visited pages) without a full page reload or React state loss. Both refreshSlot() and router.refreshSlot() are identical and return an awaitable Promise<void> (ideal for React 19's useTransition):
"use client";
import { useTransition } from "react";
import { refreshSlot, useRouter } from "dinou";
export function RefreshButton() {
const router = useRouter();
const [isPending, startTransition] = useTransition();
return (
<div className="flex gap-2">
{/* Option 1: Standalone + awaitable inside useTransition (respects server TTL) */}
<button
disabled={isPending}
onClick={() =>
startTransition(async () => {
await refreshSlot("analytics-widget");
})
}
>
{isPending ? "Refreshing..." : "Refresh Metrics"}
</button>
{/* Option 2: Force fresh (bypasses server slot TTL immediately) */}
<button onClick={() => router.refreshSlot("analytics-widget", { fresh: true })}>
Force Fresh
</button>
{/* Option 3: Wildcard "*" refreshes all mounted slots + slots cached in client session */}
<button onClick={() => refreshSlot("*")}>
Refresh All Slots
</button>
</div>
);
}refreshSlot options, router.refreshSlot, and wildcard "*" work:refreshSlot vs. router.refreshSlot (Identical & Awaitable): router.refreshSlot(id, opts) is a direct alias for refreshSlot(id, opts)—both execute the exact same code and return a Promise<void> that resolves when the slot finishes updating. Prefer standalone refreshSlot when your component doesn't otherwise need useRouter() (avoiding subscribing the component to router context changes) or when calling it outside React components (e.g., inside WebSocket/SSE listeners, polling intervals, utility functions, or external state stores like Zustand); use router.refreshSlot for convenience when you already have const router = useRouter() in scope.refreshSlot(idOrTag) (Default): Refreshes the client DOM with the server's current state. If the slot's server-side TTL (e.g. revalidate={300}) has not expired, it returns the cached server UI without touching your database (protecting against button spam and traffic spikes).refreshSlot(idOrTag, { fresh: true }) (Bypass): Hard revalidation. Forces the server to ignore any unexpired TTL, immediately re-run the server component's queries against your database, update the server cache, and update the client DOM in place.refreshSlot("*") (Wildcard): Refreshes all <DinouCacheSlot> instances currently mounted on screen (across the active page.tsx, layout.tsx, and parallel @slot routes) and refreshes in the background any slots cached in memory in the client SPA session from previously visited pages, so navigating back to those pages renders updated data immediately. ⚠️ Avoid combining "*" with { fresh: true } in production: it triggers a fan-out of requests for every mounted and session-cached slot while forcing all of them to bypass their server TTL and hit your database simultaneously. Reserve { fresh: true } for specific slot IDs or tags.refreshSlot() for the same slot resolve out of order—for example, a user clicks a filter that triggers a slow query ("all", taking 500ms) and immediately clicks another filter that triggers a fast query ("favorites", taking 30ms), or a slow refreshSlot(id, { fresh: true }) is followed by a fast cached refreshSlot(id) after a mutation—Dinou tracks a per-slot request counter so the latest request always wins and a slower earlier response never overwrites newer UI on screen.revalidateTag)Server mutations purge and update cached slots globally via revalidateTag() (imported from "dinou/server"). Any subsequent request or navigation automatically receives the new cached slot—while optionally calling refreshSlot() in the client updates the already-mounted DOM on the current user's screen in place:
"use server";
import { revalidateTag } from "dinou/server";
export async function publishPost(formData: FormData) {
const content = formData.get("content") as string;
await db.posts.insert({ content, createdAt: new Date() });
// Standalone server invalidation: purges & updates tagged slots/shells
// so any subsequent page load or navigation gets the fresh cache automatically
await revalidateTag("feed");
}"use client";
import { refreshSlot } from "dinou";
import { publishPost } from "./actions";
export function PostCreator() {
const handleSubmit = async (formData: FormData) => {
// 1. Mutate & update cache on server
await publishPost(formData);
// 2. Optional: if the feed slot is already mounted on this screen,
// update it in place right now without reloading or navigating
refreshSlot("feed-widget");
};
return (
<form action={handleSubmit}>
<input name="content" placeholder="What's new?" />
<button type="submit">Publish</button>
</form>
);
}revalidateTag vs. Optional refreshSlot:await revalidateTag("feed") (Standalone on Server): Purges the slot cache and updates any affected static shells on the server (re-running only the invalidated slot without re-executing page.tsx). You do not need refreshSlot() for future page loads or navigations—they automatically receive the new cached version.refreshSlot("feed-widget") (Optional on Client): Only needed when the user triggering the Server Function already has that slot mounted on their current screen and you want their open DOM to update in place immediately (without a page reload or navigation, and without needing { fresh: true }).refreshSlot)When a <DinouCacheSlot revalidate={N}> TTL expires, Dinou adapts its refresh strategy to the trigger so TTFB is never blocked:
Applies to unwrapped slots in Static/ISR pages and <Suspense>-wrapped slots on Dynamic SSR pages (where the fallback is shown only on a cold cache miss). When the TTL expires, the next incoming request serves the cached slot immediately inline (0 fallback flash) and starts a non-blocking background SWR refresh.
When a user clicks a button calling refreshSlot() on an expired slot (or with { fresh: true }), the server awaits the new slot render, updates the cache, and returns the fresh UI directly while preserving the existing DOM and client state (zero skeleton flash).
💡 For how expired slot TTLs behave inside PPR <Suspense> holes, see Section 6.1 (Cached Dynamic Holes vs. Static Shell Slots).
<DinouCacheSlot>Wrapping the entire page.tsx body inside a single slot reinvents route-level ISR. Declare export const revalidate = 300 in page_functions.ts instead.
Never wrap private per-user data (such as a user's cart or session profile) with a fixed, unparameterized slot ID (e.g., id="user-cart") and revalidate >= 1: because the server caches by id, User B would receive User A's cached slot. Either include the user identifier in the ID (id={`cart-${userId}`}) or use revalidate={0}.
Partial Prerendering (PPR) is Dinou's Temporal Segmentation axis: instead of forcing a route to be 100% build-time static or 100% request-time dynamic, PPR splits a single route across time. It delivers the pre-rendered Static Shell instantly at 0ms, while streaming Dynamic <Suspense> Holes in parallel over the same HTTP response connection.
<Suspense> Boundary RuleIn Dinou, React <Suspense> is the single syntactic boundary separating the build-time Static Shell from request-time Dynamic PPR Holes inside any ppr = true segment (page.tsx or layout.tsx):
Everything outside <Suspense>—including getProps, top-level async Page/Layout components, unwrapped child async Server Components, synchronous <Suspense> boundaries, and unwrapped <DinouCacheSlot revalidate={N}>—is awaited at build/revalidation time and baked into the initial Static Shell.
⚠️ Reading req.cookies, req.headers, req.query, calling useSearchParams() in a Server Component, or rendering <DinouCacheSlot revalidate={0}> outside <Suspense> triggers a Full-Route Dynamic Bailout (rendering the route dynamically per request).
Inside a ppr = true segment, a <Suspense> boundary automatically becomes a Dynamic PPR Hole whenever it wraps:
async Server Component (postpones at its very first await with zero build latency—even if it never reads cookies or headers)."use client") receiving an un-awaited Promise prop (or array of Promises, passed from a Server Component or getProps and unwrapped via React 19's use(promise)).async) reading request APIs (getContext() cookies/headers/query, or useSearchParams()) or rendering <DinouCacheSlot revalidate={0}>. (In contrast, calling useSearchParams() inside a "use client" component—even when wrapped in <Suspense>—stays in the Static Shell without opening a server hole, hydrating cleanly both in the shell and inside holes before syncing URL query params in the browser.)💡 Core Takeaway: The behavioral difference between "ppr: false" and "ppr: true" occurs inside <Suspense>: when "ppr: false", async boundaries resolve into static HTML at build time; when "ppr: true", they become streaming holes unless opted out via noDynamic().
<Suspense fallback={...}> skeletons for each dynamic hole.<Suspense> holes in parallel on the server (skipping static noDynamic() boundaries in 0ms).// src/store/page.tsx (with export const ppr = true in page_functions.ts)
import { Suspense } from "react";
import { getContext } from "dinou/server";
import db from "@/lib/db";
import { CartBadgeSkeleton, StockSkeleton, ReviewsSkeleton } from "@/components/skeletons";
import { ProductReviews } from "./product-reviews";
// 1. Unwrapped async Server Component (OUTSIDE <Suspense>) -> Baked into Static Shell at build time!
async function FeaturedCatalogBanner() {
const banner = await db.catalog.getFeaturedBanner();
return <section className="banner">{banner.title}</section>;
}
// 2. Async Server Component (INSIDE <Suspense>, no cookies) -> Dynamic PPR Hole by default!
async function RealtimeInventoryTicker() {
const stock = await db.inventory.getGlobalCount();
return <div className="stock-ticker">In Stock Now: {stock}</div>;
}
// 3. Request-aware Component (INSIDE <Suspense>, reads cookies) -> Dynamic PPR Hole!
async function LiveCartBadge() {
const sessionToken = getContext().req.cookies["session_id"];
const cart = await db.carts.findActive(sessionToken);
return <div className="cart-badge">Items: {cart?.itemCount ?? 0}</div>;
}
export default async function StorePage() {
// 4. Start an async query WITHOUT await and pass the raw Promise to a Client Component
const reviewsPromise = db.reviews.getLatest();
return (
<main className="container">
{/* Resolved at build time into the Static Shell */}
<FeaturedCatalogBanner />
{/* Postponed at first await -> Fallback in Static Shell, streamed live on every request */}
<Suspense fallback={<StockSkeleton />}>
<RealtimeInventoryTicker />
</Suspense>
{/* Cookie access quarantined inside <Suspense> -> Streamed per user without full-route bailout */}
<Suspense fallback={<CartBadgeSkeleton />}>
<LiveCartBadge />
</Suspense>
{/* Un-awaited Promise passed to a Client Component -> Registered as a Dynamic PPR Hole! */}
<Suspense fallback={<ReviewsSkeleton />}>
<ProductReviews reviewsPromise={reviewsPromise} />
</Suspense>
</main>
);
}// src/store/product-reviews.tsx
"use client";
import { use } from "react";
interface Review {
id: string;
author: string;
rating: number;
}
// Unwraps the streamed Promise on the client via React 19's use() hook
// (Works identically when an un-awaited Promise is returned from getProps!)
export function ProductReviews({
reviewsPromise,
}: {
reviewsPromise: Promise<Review[]>;
}) {
const reviews = use(reviewsPromise);
return (
<ul className="reviews-list">
{reviews.map((r) => (
<li key={r.id}>
{r.author} — {r.rating}/5
</li>
))}
</ul>
);
}<Suspense> Opt-Out (noDynamic()) & Runtime PerformanceSuppose a ppr = true page has both a Dynamic PPR Hole (e.g., a live user header) and a heavy static async Server Component (e.g., compiling Markdown with syntax highlighting). On every request, after flushing the 0ms Static Shell, Dinou traverses page.tsx's component tree on the server to locate and stream the dynamic holes:
async component is unwrapped (outside <Suspense>): Its HTML is in the Static Shell, but during the runtime tree traversal to reach the dynamic holes, the server still has to await and re-run that unwrapped async component!<Suspense> (default): Inside a ppr = true segment, <Suspense> turns it into a Dynamic PPR Hole instead of baking it into the Static Shell.To get the best of both worlds, wrap the static component in <Suspense> and call noDynamic() (exported from "dinou/server", "dinou", and route-local "./dinou") synchronously at the top of the component before its first await:
noDynamic() opts the enclosing <Suspense> boundary out of becoming a Dynamic Hole, pre-rendering its resolved UI directly into the Static Shell. Because it is already resolved in the Static Shell, its <Suspense> fallback is never shown in production (neither on initial load nor on SPA navigation; it is only used when streaming on demand in dinou dev).page.tsx to stream the other dynamic holes on the page, as soon as it enters that static <Suspense> boundary and hits noDynamic(), it immediately aborts and skips that entire subtree in 0ms without re-executing its async work!import { Suspense } from "react";
import { noDynamic } from "dinou/server"; // or from "dinou" / "./dinou"
import { LiveUserBookmarkButton } from "./bookmarks";
async function StaticMarkdownArticle({ slug }: { slug: string }) {
// 1. Build time: opts the enclosing <Suspense> into the Static Shell (no fallback in prod)
// 2. Runtime: aborts & skips this subtree in 0ms when streaming <LiveUserBookmarkButton />!
// Must be called synchronously BEFORE the first await!
noDynamic();
const markdown = await readMarkdownFromDisk(slug);
const html = await highlightCodeBlocks(markdown);
return <article dangerouslySetInnerHTML={{ __html: html }} />;
}
export default function DocPage() {
return (
<main>
{/* Dynamic PPR Hole (streams per request) */}
<Suspense fallback={<span>Loading bookmark status...</span>}>
<LiveUserBookmarkButton slug="intro" />
</Suspense>
{/* Static Shell <Suspense> via noDynamic() (baked at build time, skipped in 0ms at runtime) */}
<Suspense fallback={<p>Loading article...</p>}>
<StaticMarkdownArticle slug="intro" />
</Suspense>
</main>
);
}noDynamic()await: Because Dinou inspects the component's synchronous execution frame right when it returns its initial Promise, calling noDynamic() after the first await is too late and the boundary will still become a Dynamic Hole.noDynamic() in a parent component inside <Suspense> automatically opts out all child async components (and un-awaited Promise props) inside that same <Suspense> boundary. If that static <Suspense> boundary contains a nested inner <Suspense> boundary without noDynamic(), the outer wrapper bakes into the Static Shell while the inner boundary cleanly streams as a dynamic hole!noDynamic() boundary reads req.cookies, req.headers, req.query, calls useSearchParams(), or renders <DinouCacheSlot revalidate={0}>, Dinou overrides noDynamic() and turns the boundary into a Dynamic PPR Hole to prevent leaking request data into the shared Static Shell.In Dinou, ppr defaults to false across all route segments (every root layout.tsx, nested layout.tsx, and leaf page.tsx), and you can change this project-wide default to true in dinou.config.ts (or .js) via defineConfig({ ppr: true }) (so every layout and page uses PPR automatically unless a specific segment opts out with export const ppr = false). Each segment resolves its ppr flag—which accepts a boolean (true | false) or a sync/async function (() => boolean | Promise<boolean>)—strictly from its own configuration file (layout_functions.ts or page_functions.ts) without parent-to-child inheritance, falling back directly to dinou.config.ts:
page_functions.ts or layout_functions.ts: ppr = true | false | (() => boolean | Promise<boolean>))Segment OverridedefineConfig({ ppr: true | false }) — defaults to false)Global FallbackSetting export const ppr = true in src/dashboard/layout_functions.ts enables PPR only for src/dashboard/layout.tsx (and its parallel @slot routes). Child layouts and child pages do not inherit it automatically.
A single URL route can freely combine "ppr: true" and "ppr: false" segments—for example, a "ppr: true" layout streaming a live user header around a "ppr: false" static page, or a static layout wrapping a "ppr: true" streaming page.
On mixed routes, <Suspense> boundaries inside a "ppr: false" segment resolve statically at build time without becoming PPR holes, and reading dynamic request APIs (cookies/headers/query, RSC useSearchParams(), or revalidate={0}) inside a "ppr: false" segment—even inside <Suspense>—triggers a Full-Route Dynamic Bailout as expected.
layout_functions.ts + <DinouCacheSlot>)When you combine Horizontal Segmentation (independent layouts, parallel @sidebar routes, and pages) with Vertical Segmentation (<DinouCacheSlot> & refreshSlot) on standard routes (ppr = false), you can place independent cached slots inside both layout.tsx (or @sidebar) and page.tsx—and any slot updated on screen via refreshSlot() stays updated in the client router's cache when navigating back and forth between pages.
@sidebar Parallel Slots & Cross-Axis Shared TagsCombining Horizontal and Vertical segmentation gives you four high-impact capabilities:
Place <DinouCacheSlot> inside layout.tsx, nested sub-layouts, or parallel routes (@sidebar/page.tsx). Calling revalidateTag("sidebar-slot") + refreshSlot("sidebar-slot") updates that widget in place without re-executing layout.tsx, layout_functions.ts, or the active page.tsx.
A slot in layout.tsx (e.g., a header credit counter) and a slot in page.tsx (e.g., a usage breakdown table) can share a tag (tags={["credits-sync"]}). A single call to await revalidateTag("credits-sync") + refreshSlot("credits-sync") updates both the layout widget and the page widget in unison!
Inside a "ppr: false" static page, use short-TTL or nested Outer → Inner slots (e.g., revalidate={30} inside a 1-hour page) to keep the host page static while refreshing volatile widgets via SWR. Using revalidate={0} on a "ppr: false" page opts that page into Dynamic SSR (while keeping the parent layout.tsx and sibling revalidate >= 1 slots cached—or pair revalidate={0} with ppr = true + <Suspense> in Section 6 for a 0ms Static Shell).
Conversely, when you call revalidatePage("/workspace") or revalidateLayout("/workspace") to update the host page or layout, Dinou automatically reuses all unexpired <DinouCacheSlot> caches without re-running their expensive database queries!
// Cached for 1h via layout_functions.ts
import type { LayoutProps } from "./dinou";
import { DinouCacheSlot } from "dinou/server";
import { HeaderCreditsBadge } from "./widgets";
export default function WorkspaceLayout({
children,
sidebar, // Automatically inferred from @sidebar!
}: LayoutProps) {
return (
<div className="workspace-shell">
<header>
{/* Cross-axis shared tag "credits-sync": updates alongside page slot! */}
<DinouCacheSlot id="header-credits" tags={["credits-sync", "header-only"]} revalidate={300}>
<HeaderCreditsBadge />
</DinouCacheSlot>
</header>
<aside>{sidebar}</aside>
<main>{children}</main>
</div>
);
}// Cached for 1h via page_functions.ts
import { DinouCacheSlot } from "dinou/server";
import { UsageBreakdownTable, DepartmentPanel, LiveQuotaTicker } from "./widgets";
export default function WorkspacePage() {
return (
<section className="space-y-6">
{/* Shares "credits-sync" tag with the layout header slot */}
<DinouCacheSlot id="page-usage-table" tags={["credits-sync", "usage-only"]} revalidate={300}>
<UsageBreakdownTable />
</DinouCacheSlot>
{/* Nested Outer (1h) -> Inner (30s) slots inside a cached static host page */}
<DinouCacheSlot id="workspace-dept-outer" tag="dept-outer" revalidate={3600}>
<DepartmentPanel>
<DinouCacheSlot id="workspace-quota-ticker" tag="quota-ticker" revalidate={30}>
<LiveQuotaTicker />
</DinouCacheSlot>
</DepartmentPanel>
</DinouCacheSlot>
</section>
);
}On standard routes, Dinou's client router caches visited pages in memory so round-trip soft navigation (Page A → Page B → Page A) completes in 0ms with 0 network requests. Dinou keeps your live-refreshed <DinouCacheSlot> state in sync across those navigations automatically:
Page A → Page B → Page A): If a user refreshes a slot on Page A (e.g., refreshSlot("page-usage-table") from the snippet above), navigates to Page B, and clicks back to Page A, Dinou remembers and renders the refreshed slot state immediately (with 0 network requests) instead of reverting to the initial pre-refresh page snapshot.Page A Slot While Viewing Page B: If the user has already visited Page A, navigates to Page B (so Page A's "page-usage-table" slot is not currently on screen), and triggers an action on Page B that calls refreshSlot("page-usage-table") (or its tag refreshSlot("usage-only")), Dinou automatically refreshes Page A's slot in the background. When the user navigates back to Page A, the updated widget is already waiting in memory!layout_functions.ts + PPR)When you combine Horizontal Segmentation and Partial Prerendering (PPR) (even without <DinouCacheSlot>), every layout, parallel route (@sidebar), and page resolves its ppr mode independently—allowing both segments to maintain independent Static Shells and stream parallel <Suspense> holes in a single HTTP response, or to mix "ppr: true" and "ppr: false" segments freely on the same URL route.
In a segmented PPR route hierarchy, your layout and your page each have their own independent static shell cache, TTL (revalidate), and invalidation tags (getCacheTags), while any <Suspense> holes inside the layout, @sidebar, and page stream in parallel on every request:
import { Suspense } from "react";
import type { LayoutProps } from "./dinou";
import { getContext } from "dinou/server";
async function LiveUserHeaderHole() {
// Dynamic Hole in Layout: Streams on every request & on router.refresh({ layout: true })
const user = getContext().req.cookies["session_user"] ?? "guest";
return <span>Signed in as {user}</span>;
}
export default function DashboardLayout({
children,
sidebar,
orgName,
}: LayoutProps<{ orgName: string }>) {
return (
<div className="dashboard-shell">
<header>
<h1>{orgName}</h1> {/* Pre-rendered in Layout Static Shell for 1h */}
<Suspense fallback={<span>Loading user...</span>}>
<LiveUserHeaderHole />
</Suspense>
</header>
<aside>{sidebar}</aside> {/* Can also host its own <Suspense> holes in @sidebar/page.tsx! */}
<main>{children}</main>
</div>
);
}import type { LayoutFunctions } from "./dinou";
export const ppr: LayoutFunctions["ppr"] = true;
export const revalidate: LayoutFunctions["revalidate"] = 3600; // Layout static shell cached for 1h
export const getCacheTags: LayoutFunctions["getCacheTags"] = ["dashboard-layout-tag"];
export async function getProps() {
// Runs ONLY at build time or when "dashboard-layout-tag" / revalidateLayout is triggered
return { orgName: await db.orgs.getDefaultName() };
}import type { PageFunctions } from "./dinou";
// Each segment resolves ppr independently (or uses the global default from dinou.config.ts)
export const ppr: PageFunctions["ppr"] = true;
export const revalidate: PageFunctions["revalidate"] = 300; // Page static shell cached independently for 5m
export const getCacheTags: PageFunctions["getCacheTags"] = ["dashboard-home-tag"];Because Horizontal Segmentation separates the Layout from the Page and PPR separates the Static Shell from the Dynamic <Suspense> Holes, a segmented PPR route can have up to four independent parts: Layout Shell, Layout Holes, Page Shell, and Page Holes (or a subset on mixed routes where only the layout or only the page sets ppr = true). The table below summarizes how each client refresh, server revalidation, and soft navigation operation targets only the relevant parts without re-executing or re-fetching the rest:
| Operation / API | Effect on Layout Shell & Layout Holes | Effect on Page Shell & Page Holes |
|---|---|---|
| router.refresh() | Untouched (0 layout requests; layout client state preserved) | Page static shell stays cached; Page dynamic <Suspense> holes re-execute live with current cookies/query! |
| router.refresh({ layout: true }) | Layout static shell stays cached; Layout & @sidebar dynamic <Suspense> holes re-execute live! | Page static shell stays cached; Page dynamic <Suspense> holes re-execute live! |
| revalidatePage("/dashboard") (or Page Tag / Page TTL) | 0 layout.tsx executions! Reuses the cached layout shell | Regenerates the page static shell while preserving dynamic hole streaming |
| revalidateLayout("/dashboard") (or Layout Tag / Layout TTL) | Regenerates the layout static shell immediately (and lazily updates nested sub-layouts on demand when visited) | 0 page.tsx executions! When visited, child pages (both "ppr: true" and "ppr: false") lazily combine the new layout with their existing cached page |
| Soft Nav: PPR Page ↔ Static Non-PPR Page ("ppr: false") | Shared parent PPR layout stays mounted with 0 layout network requests | Seamlessly navigates between streamed PPR pages and 100% static non-PPR child pages |
| Mixed Route: Static Layout ("ppr: false") + PPR Page ("ppr: true") | Layout (including any layout <Suspense>) resolves statically at build time into the shell | Page delivers its 0ms static shell and streams its own dynamic <Suspense> holes per request |
<DinouCacheSlot> + PPR)With PPR alone, a PPR segment only has two parts: the 0ms Static Shell and Dynamic <Suspense> Holes that re-execute from scratch on every request (and can only be refreshed all at once via router.refresh()). Combining all primitives of the Temporal Axis (ppr = true, <Suspense>, noDynamic(), request data) with the Vertical Axis (<DinouCacheSlot>, revalidate={N} vs. revalidate={0}, and nested slots) produces 7 possible combinations:
<DinouCacheSlot revalidate={N}> Outside <Suspense> (or Wrapping an Inner <Suspense>): Resolves at build time into the Static Shell (0ms TTFB, no fallback). Unlike the rest of the Static Shell, it has its own independent TTL/tags (updating via Background SWR without re-executing page.tsx) and supports in-place client refresh via refreshSlot(id) (Section 6.1, Pattern B).<Suspense> Wrapping <DinouCacheSlot revalidate={N}> + noDynamic(): Calling noDynamic() prevents the outer <Suspense> from postponing into a PPR hole. The slot stays in the Static Shell (same as #1), and Dinou also skips that <Suspense> branch in 0ms at runtime when streaming other dynamic holes on the route (Section 6.1, Pattern B).<Suspense> Wrapping <DinouCacheSlot revalidate={N}> (Default): Becomes a Cached Dynamic PPR Hole. The Static Shell flushes immediately with the <Suspense> fallback, and the hole streams from the server slot cache in ~2ms while its TTL is valid—re-executing live in the stream on expiry or revalidateTag without touching the Static Shell (Section 6.1, Pattern A).<DinouCacheSlot revalidate={N}> Inside a Personalized Dynamic <Suspense> Hole: When a <Suspense> hole must run live on every request because a Server Component reads user-specific request data (req.cookies, req.headers, req.query, or useSearchParams()), placing a parameterized <DinouCacheSlot> inside it caches the expensive shared UI (~2ms) across users who share that parameter (Section 6.2).<Suspense> Wrapping <DinouCacheSlot revalidate={0}> (Surgically Refreshable Live Hole): With revalidate={0}, the slot never caches on the server and streams live on every request as a Dynamic PPR Hole (without breaking the Static Shell). Unlike a plain <Suspense> hole (which can only be refreshed by re-running all page holes via router.refresh()), wrapping it in <DinouCacheSlot id="live-hole" revalidate={0}> lets you refresh only that specific hole from the client with refreshSlot("live-hole") (Section 6.2).Outer <DinouCacheSlot> → Inner <DinouCacheSlot>): You can nest a short-TTL slot (e.g., revalidate={60}) inside a long-TTL slot (e.g., revalidate={3600}) in either the Static Shell or a Dynamic Hole. When the inner slot expires or is refreshed, Dinou re-renders only the inner child slot and splices it into the cached parent slot without re-running the parent (Section 6.2).<DinouCacheSlot revalidate={0}> (or RSC Request Data Access) Outside <Suspense> (Full-Route Bailout): Because there is no outer <Suspense> boundary to isolate it into a PPR hole, placing revalidate={0} or reading cookies/headers/query/RSC useSearchParams() outside <Suspense> forces a Full-Route Dynamic Bailout (the entire route falls back to per-request SSR).<Suspense> vs. <DinouCacheSlot>)Inside a ppr = true segment (page or layout), the nesting order between <Suspense> and <DinouCacheSlot revalidate={N}> (where N >= 1 or omitted) determines whether the slot becomes a Cached Dynamic PPR Hole or a Static Shell Slot:
<Suspense fallback={...}> <DinouCacheSlot id="metrics" revalidate={60}> <HeavyMetricsGraph /> </DinouCacheSlot> </Suspense>
revalidateTag: Instead of serving stale data via SWR, the Static Shell stays 100% intact (0ms TTFB) with its skeleton fallback while the hole re-executes live in the stream and delivers 100% fresh data!<DinouCacheSlot id="pricing" revalidate={60}> <PricingTable /> </DinouCacheSlot>
revalidateTag: Uses Background SWR to refresh only that slot and update the Static Shell without re-executing page.tsx.What if a dynamic PPR <Suspense> hole reads user-specific request data in a Server Component (req.cookies, req.headers, req.query, or useSearchParams()), and inside that personalized hole you also need to render an expensive shared calculation or a nested Outer → Inner slot hierarchy? Or what if you have a 100% live uncached hole that you want to refresh individually via refreshSlot(id) without re-running every other hole on the page via router.refresh()?
Simply place parameterized <DinouCacheSlot> boundaries inside the personalized component, or wrap a live hole in <DinouCacheSlot revalidate={0}> inside <Suspense>:
// src/feed/page.tsx (with export const ppr = true in page_functions.ts)
import { Suspense } from "react";
import { DinouCacheSlot, getContext } from "dinou/server";
async function PersonalizedDepartmentHole() {
// Runs live on EVERY request with the user's cookies & query params
const ctx = getContext();
const user = ctx.req.cookies["session_user"] ?? "guest";
const dept = ctx.req.cookies["dept_id"] ?? "general";
return (
<section className="space-y-4">
<h2>Welcome back, {user} (Department: {dept})</h2>
{/* Combination #4: Cached across all users in the same department for 1h */}
<DinouCacheSlot id={`dept-outer-${dept}`} tag={`dept-${dept}`} revalidate={3600}>
<div className="dept-panel">
<QuarterlyDepartmentSummary dept={dept} />
{/* Combination #6: Nested inner slot with a fast 60s TTL inside the 1h outer slot */}
<DinouCacheSlot id={`dept-ticker-${dept}`} tag="live-kpi" revalidate={60}>
<DepartmentKpiTicker dept={dept} />
</DinouCacheSlot>
</div>
</DinouCacheSlot>
</section>
);
}
export default function FeedPage() {
return (
<main>
{/* Combination #1: Static Shell Slot (baked into initial HTML at 0ms TTFB) */}
<DinouCacheSlot id="announcement-banner" tag="banner" revalidate={3600}>
<GlobalAnnouncementBanner />
</DinouCacheSlot>
{/* Combination #4 & #6: Personalized Dynamic Hole containing nested cached slots */}
<Suspense fallback={<div>Streaming your department workspace...</div>}>
<PersonalizedDepartmentHole />
</Suspense>
{/* Combination #5: Live uncached PPR hole (revalidate={0}) that can be refreshed
individually via refreshSlot("live-inbox") without refreshing the other holes! */}
<Suspense fallback={<div>Loading live inbox...</div>}>
<DinouCacheSlot id="live-inbox" revalidate={0}>
<LiveUserInbox />
</DinouCacheSlot>
</Suspense>
</main>
);
}In Triple Synergy, all three dimensions operate simultaneously on the same route tree: multi-level Horizontal Layouts (layout_functions.ts), Per-Segment Temporal PPR ("ppr: true" on layouts and/or pages alongside "ppr: false" static segments), and Vertical <DinouCacheSlot> boundaries placed inside layout shells, page static shells, and streamed dynamic <Suspense> holes.
Below, a single route tree combines a segmented PPR Layout (hosting a layout-level <DinouCacheSlot>) with a PPR Page (hosting a Static Shell <DinouCacheSlot>, a Cached Dynamic Hole, and an uncached per-user Dynamic Hole):
import type { LayoutProps } from "./dinou";
import { DinouCacheSlot } from "dinou/server";
import { ClusterRegionSelector, IncidentAlertBar } from "./layout-widgets";
export default function TelemetryLayout({ children }: LayoutProps) {
return (
<div className="telemetry-workspace">
<header className="flex items-center justify-between">
{/* Layout-level Static Shell Slot: shared across all /telemetry/* routes */}
<DinouCacheSlot id="incident-bar" tag="incident-alert" revalidate={120}>
<IncidentAlertBar />
</DinouCacheSlot>
<ClusterRegionSelector /> {/* Client Component: state preserved across soft nav */}
</header>
{children}
</div>
);
}import type { LayoutFunctions } from "./dinou";
export const ppr: LayoutFunctions["ppr"] = true;
export const revalidate: LayoutFunctions["revalidate"] = 3600;
export const getCacheTags: LayoutFunctions["getCacheTags"] = ["telemetry-layout"];import { Suspense } from "react";
import { DinouCacheSlot, getContext } from "dinou/server";
import { GlobalStatusBanner, HeavyMetricsGraph, GraphSkeleton } from "./widgets";
async function UserAuditTrail() {
const userId = getContext().req.cookies["user_id"] ?? "anon";
const logs = await db.audit.getRecentForUser(userId);
return <pre>{JSON.stringify(logs, null, 2)}</pre>;
}
export default function TelemetryPage() {
return (
<main className="container py-8 space-y-6">
{/* A. Page Static Shell Micro-ISR Slot: Baked into initial HTML, 300s Background SWR */}
<DinouCacheSlot id="global-status" tag="status-banner" revalidate={300}>
<GlobalStatusBanner />
</DinouCacheSlot>
{/* B. Cached Dynamic PPR Hole: Skeleton in initial HTML, ~2ms cached stream for 60s */}
<Suspense fallback={<GraphSkeleton />}>
<DinouCacheSlot id="operations-telemetry" tag="telemetry" revalidate={60}>
<HeavyMetricsGraph />
</DinouCacheSlot>
</Suspense>
{/* C. Uncached Per-User PPR Hole: Streamed live per request */}
<Suspense fallback={<div>Loading your audit trail...</div>}>
<UserAuditTrail />
</Suspense>
</main>
);
}import type { PageFunctions } from "./dinou";
// Enable PPR for this page segment (or set ppr: true globally in dinou.config.ts)
export const ppr: PageFunctions["ppr"] = true;
export const getCacheTags: PageFunctions["getCacheTags"] = ["telemetry-page"];Outer layout shell, page shell, static slots, and fallback skeletons arrive immediately from Dinou's cache.
Visitors receive the precalculated slot stream almost instantly over the same HTTP connection.
10,000 concurrent visitors/min trigger only 1 shared telemetry DB query per 60s TTL.
Because Dinou tracks layout slots, page static-shell slots, and dynamic-hole slots independently, invalidating any piece of a Triple Synergy route never triggers unnecessary work in the rest of the tree:
await revalidateTag("telemetry")): Clears only that slot's cache. Neither the static page shell, page.tsx, nor layout.tsx is touched—preserving 0ms TTFB while the hole streams fresh data on the next request.await revalidateTag("status-banner")): Re-renders only <GlobalStatusBanner /> and updates the page's static shell without re-executing page.tsx, page_functions.ts, or layout.tsx.await revalidateTag("incident-alert")): Re-renders only <IncidentAlertBar /> inside the layout without re-executing layout.tsx, and automatically updates both PPR and Static child routes on their next visit without re-executing any child page.tsx.refreshSlot & router.refresh): Calling refreshSlot("incident-bar"), refreshSlot("global-status"), or refreshSlot("operations-telemetry") updates that exact widget in place while preserving Client Component useState across the layout, static shell, and dynamic holes—with zero hydration mismatch on subsequent F5 reloads.Summary of all 7 non-empty architectural combinations (2³ − 1 = 7) across the Horizontal (H), Vertical (V), and Temporal (T) axes:
| # / Combination | How to Configure | TTFB | Surgical Refresh & Expiry | Best For |
|---|---|---|---|---|
| 1. Horizontal Only (H) | layout_functions.ts + page_functions.ts | ~1.20ms (0 Layout Re-fetches on Soft Nav) | revalidateLayout / revalidatePage + Automatic HTML Re-composition | Multi-page workspaces, persistent navbars, dynamic child pages under static layouts |
| 2. Vertical Only (V) | <DinouCacheSlot id tag revalidate> | ~1.45ms (Static Shell) or ~2ms (SSR Hit) | Background SWR + revalidateTag + live in-place refreshSlot() | Isolating heavy SQL/API widgets inside SSR dashboards or slow-ISR catalog pages |
| 3. Temporal Only (T / PPR) | ppr = true + <Suspense> (+ noDynamic) | ~2.42ms (0ms Cached Static Shell) | Instant Static Shell + 100% real-time parallel <Suspense> holes | Instant landing/store shells with personalized per-user holes or streamed Client Promise props |
| 4. Pairwise #1: H + V (Non-PPR) | layout_functions.ts + <DinouCacheSlot> in Layout/@sidebar/Page | ~1.45ms (SSR) / 0ms (Cached Soft Nav) | Cross-axis shared tags + slot state persisted across Page A → B → A | Rich SPA apps with header/sidebar widgets, cross-route state, and zero-network back/forward nav |
| 5. Pairwise #2: H + T (Layouts + PPR) | ppr = true per segment (or in dinou.config.ts) across layout_functions.ts / page_functions.ts | ~2.42ms (Independent Layout & Page Shells) | router.refresh() (page holes) vs. { layout: true } + Independent shell revalidation | Multi-level portals mixing PPR layouts, @sidebar holes, PPR pages, and static ("ppr: false") pages |
| 6. Pairwise #3: V + T (Slots + PPR) | ppr = true + <DinouCacheSlot> (in Shell or in <Suspense>) | ~2.42ms (Shell) + ~2ms (Cached Hole) | Shell slots (SWR) + Cached Dynamic Holes (stream) + Slots inside per-user holes | Pages combining 0ms static shell widgets, shared heavy dynamic holes, and personalized feeds |
| 7. Triple Synergy: H + V + T | layout_functions.ts + page_functions.ts + ppr = true + <DinouCacheSlot> | ~2.42ms (Shell) + ~2ms (Cached Hole) + 0 Layout Fetches | 4-Way Surgical Invalidation (Layout, Page, Shell Slot, Hole Slot) with 0 collateral rebuilds | Large-scale, high-concurrency e-commerce and real-time telemetry platforms |
<Suspense> + <DinouCacheSlot> + noDynamic() Behavior Matrix| Component Pattern | Behavior in a "ppr: true" Segment | Behavior in a "ppr: false" Segment |
|---|---|---|
| Unwrapped async Server Component (outside <Suspense>) | Static Shell (pre-rendered into initial HTML at build time) | Static HTML (pre-rendered at build time) |
| <Suspense> + async Server Component (default) | Dynamic PPR Hole (fallback in initial HTML, streams live per request) | Static HTML (resolved at build time into initial HTML) |
| <Suspense> + Client Component ("use client") with un-awaited Promise prop (use()) | Dynamic PPR Hole (fallback in initial HTML, streams live per request to use()) | Static HTML (resolved at build time; or streamed per request on Dynamic SSR) |
| <Suspense> + async Server Component (or Promise prop) + noDynamic() | Static Shell (pre-rendered into initial HTML + 0ms runtime skip) | Static HTML (resolved at build time into initial HTML) |
| <DinouCacheSlot revalidate={N}> outside <Suspense> (or wrapping inner <Suspense>) | Static Shell Slot (baked into initial HTML; Background SWR on expiry) | Static Slot (baked into initial HTML; Background SWR on expiry) |
| <Suspense> wrapping <DinouCacheSlot revalidate={N}> (default) | Cached Dynamic PPR Hole (fallback in initial HTML, ~2ms cached stream; live stream refresh on expiry) | Static Slot (baked into initial HTML; Background SWR on expiry) |
| <Suspense> wrapping <DinouCacheSlot revalidate={N}> + noDynamic() | Static Shell Slot (baked into initial HTML; Background SWR on expiry) | Static Slot (baked into initial HTML; Background SWR on expiry) |
| Client Component ("use client") calling useSearchParams() (inside or outside <Suspense>) | Static Shell (does not open a server PPR hole; hydrates cleanly & syncs query in browser) | Static HTML (pre-rendered at build time; hydrates cleanly & syncs query in browser) |
| Reading cookies/headers/query, RSC useSearchParams(), or revalidate={0} inside <Suspense> (even with noDynamic) | Dynamic PPR Hole (quarantined to hole; overrides noDynamic) | Full-Route Dynamic Bailout (entire route renders dynamically per request) |
| Reading cookies/headers/query, RSC useSearchParams(), or revalidate={0} outside <Suspense> | Full-Route Dynamic Bailout (entire route renders dynamically per request) | Full-Route Dynamic Bailout (entire route renders dynamically per request) |