Executive ReferenceDinou v7
⚡ Dinou Complete Cheatsheet
At-a-glance high-density desktop reference for file conventions, dynamic route syntax, server lifecycle contracts, client navigation hooks, and architectural decision matrices.
Need deep-dive signatures and multi-line snippets?
This cheatsheet provides concise signatures and decision tables. Full implementations are documented in the API Reference.
1. File Conventions CheatsheetFilesystem
Directories inside src/app/ directly map to URL paths. Standardized file names define UI leaves, layout shells, and decoupled server contracts.
Route Components & Lifecycles
| Filename | Role | Scope | Key Responsibility |
|---|---|---|---|
| page.{tsx,jsx,ts,js} | Route Page UI | Universal | Primary UI component rendered for the route segment. Receives server props returned by getProps. |
| layout.{tsx,jsx,ts,js} | Layout Shell | Universal | Persistent UI wrapper wrapping child segments. Preserves client state across child navigations. |
| error.{tsx,jsx,ts,js} | 500 Error Page | Universal | Error UI rendered when an unhandled server or client exception occurs within this route subtree. |
| not_found.{tsx,jsx,ts,js} | 404 Page | Universal | Rendered when a segment does not exist or when validateParams() returns false. Receives params and any server props returned by getProps if page_functions is present. |
| page_functions.{ts,js} | Page Server Lifecycle | Server Only | Decoupled server contract for page.tsx: getProps, revalidate, ppr, getStaticPaths, getCacheTags. |
| layout_functions.{ts,js} | Layout Server Lifecycle | Server Only | Decoupled server contract for layout.tsx: independent getProps and ppr execution. |
Hierarchical Bubble-Up: Dinou bubbles unhandled errors and 404s upward to the closest ancestor handler. A nested
src/app/blog/[slug]/not_found.tsx intercepts 404s before the root src/app/not_found.tsx.Layout Control Flags (Empty Files)
Create these empty files (zero bytes, no extension) inside a route directory to modify layout inheritance without writing custom wrapper logic:
| Flag File | Target | Architectural Effect |
|---|---|---|
| no_layout | page.tsx | Renders the page completely bare, bypassing all parent layouts. Ideal for print templates, popups, or embeddable iframes. |
| reset_layout | layout.tsx | Resets the layout stack. Discards all ancestor layouts; this folder's layout.tsx becomes the isolated new Root Layout for this branch. |
| no_layout_error | error.tsx | Renders the segment's 500 error page without any surrounding layout shells. |
| no_layout_not_found | not_found.tsx | Renders the segment's 404 not found page without any surrounding layout shells. |
Route Escaping (_prefix)
Any directory prefixed with an underscore (_folder) is completely ignored by the route compiler.
When to use Underscore Folders
Standard project folders (e.g.
components/, hooks/, utils/) do NOT require an underscore prefix; Dinou only treats a folder as a route if it contains a page.* file. Use _ exclusively to quarantine legacy or backup folders containing page.* files (e.g., src/app/_archived-v1/page.tsx).2. Route Syntax & TypesType Safety
Dinou provides zero-runtime type safety by inferring route parameter types directly from folder bracket naming conventions.
Route Patterns & Inferred Params
| Folder Pattern | Example URL | Inferred params Type | Behavior |
|---|---|---|---|
| /about | /about | {} | Static segment. Exactly matches literal path. |
| /blog/[slug] | /blog/hello-world | { slug: string } | Single required dynamic parameter. |
| /docs/[...slug] | /docs/api/routing | { slug: string[] } | Catch-all. Matches 1 or more trailing segments. |
| /shop/[[...slug]] | /shop, /shop/shoes/nike | { slug?: string[] } | Optional catch-all. Matches 0 or more trailing segments. |
| /dash/[[tab]] | /dash, /dash/billing | { tab?: string } | Optional single parameter. |
| /(auth)/login | /login | {} | Route group. Organizes files without adding a URL segment. |
Type-Safe Routing Helpers (dinou)
| Helper Type | TypeScript Signature | Purpose | API Ref |
|---|---|---|---|
| PageProps<T> | { params: RouteParams<T>, searchParams: ... } | Type signature for page.tsx default export component. | Docs |
| LayoutProps<T> | { children: React.ReactNode, params: RouteParams<T> } | Type signature for layout.tsx default export component. | Docs |
| ErrorProps<T> | { error: Error, params: RouteParams<T> } | Type signature for error.tsx page component. | Docs |
| RouteParams<T> | Extracted parameter dictionary based on string literal pattern | Typed params argument for getProps, getCacheTags, or validateParams. | Docs |
| DinouRoute | Union of concrete path strings: "/about" | "/contact" | ... | Level 1 type safety: powers IDE autocomplete & link validation for <Link href="...">. | Docs |
| DinouRoutePattern | Union of parameterized patterns: "/blog/[slug]" | ... | Level 2 type safety: generic constraint for route contract functions and props. | Docs |
3. Server Lifecycle ContractsServer Only
Contracts declared in page_functions.ts (or layout_functions.ts). Executed exclusively on the server, completely decoupled from React render passes.
Exported Contracts Table
| Exported Contract | Signature | Default | Execution & Purpose | API Ref |
|---|---|---|---|---|
| getProps(params) | (params) => Promise<T> | T | {} | Server data loader. Return value is directly passed as props to page.tsx or layout.tsx. | Docs |
| revalidate | number | false | (() => ...) | false (SSG) | Cache TTL in seconds. 0 = SSR (dynamic), >= 1 = ISR, false = Static SSG. | Docs |
| ppr | boolean | (() => boolean | Promise<boolean>) | false | Enables Partial Prerendering: static shell built at build time, dynamic holes stream via React Suspense. | Docs |
| getCacheTags(params) | (params) => string[] | Promise<string[]> | [] | Associates cache tags with the route for targeted on-demand invalidation via revalidateTag(tag). | Docs |
| getStaticPaths() | () => StaticPathItem[] | Promise<...> | [] | Pre-generates dynamic parameter combinations during build time for SSG rendering. | Docs |
| allowISG | boolean | (() => boolean | Promise<boolean>) | true | When true, ungenerated paths render on-demand on first visit. When false, ungenerated paths return 404. | Docs |
| validateParams(params) | (params) => boolean | Promise<boolean> | () => true | Route parameter gatekeeper. Returning false immediately terminates with a 404 before calling getProps. | Docs |
Revalidation Modes (SSR vs ISR vs SSG)
| Export Value | Rendering Mode | Cache Behavior | Ideal Use Case |
|---|---|---|---|
| export const revalidate = 0; | Dynamic SSR | Evaluated fresh on every HTTP request. Never cached in static storage. | User accounts, checkout pages, real-time analytics. |
| export const revalidate = 60; | ISR (Regeneration) | Served from cache for N seconds. Next visit serves stale cache and triggers background re-generation. | E-commerce product pages, news feeds, search result pages. |
| export const revalidate = false; | Static (SSG) | Prerendered at build time and cached indefinitely until purged via on-demand invalidation. | Marketing landing pages, documentation, blog posts. |
5. Server Primitives & Cachedinou & dinou/server
Server-side context providers, micro-ISR slot primitives, and cluster cache purge APIs.
getContext & DinouCacheSlot
| Export | Package | Signature | Purpose & Mechanics | API Ref |
|---|---|---|---|---|
| getContext() | dinou | () => ServerContext | null | Synchronous HTTP access via AsyncLocalStorage: req.cookies, req.headers, res.cookie(), res.setHeader(). | Docs |
| <DinouCacheSlot> | dinou/server | id, revalidate?, tag?, tags? | Micro-ISR server component. Caches an independent sub-tree without re-evaluating parent layouts or siblings. | Docs |
| defineConfig(config) | dinou | (config: DinouConfig) => DinouConfig | Type helper for dinou.config.mjs (reactStrictMode, ppr, storage, plugins). | Docs |
| Storage Adapters | dinou/server | MemoryStorage, RedisStorage | ISR storage engines for single server or distributed multi-instance clusters. | Docs |
On-Demand Cache Invalidation (dinou/server)
| Function | Target | Signature | Purge Effect | API Ref |
|---|---|---|---|---|
| revalidateTag(tag) | Tags (Pages & Slots) | (tag: string) => Promise<void> | Purges all pages and <DinouCacheSlot> components tagged with the identifier across the cluster. | Docs |
| revalidatePath(path) | Exact Route Path | (path: string) => Promise<void> | Purges the cached HTML and data for a specific pathname and triggers background re-generation. | Docs |
| revalidatePage(pattern) | Route Pattern | (pattern: string) => Promise<void> | Purges all compiled cache instances matching a route pattern or page component. | Docs |
6. Decision Matrix: When to Use WhatArchitectural Guide
Quick comparative decision tables to help you pick the right primitive for caching, navigation, and state access without trial and error.
Cache Invalidation: Which method should you call?
| Method | Caller Environment | Scope of Impact | When to Choose It |
|---|---|---|---|
| revalidateTag(tag) | Server (Action / Webhook / API) | Multi-page & multi-slot cluster | Recommended for shared data models: when updating a database record (e.g., product or article) that appears across lists, detail pages, and sidebar widgets. |
| revalidatePath(path) | Server (Action / Webhook / API) | Single static route path | When you know the exact URL that changed and want to purge its HTML/JSON (e.g. "/pricing" or "/about"). |
| refreshSlot(slotId) | Client Component (Browser) | Single targeted slot on current page | Zero layout re-render: when an interactive client widget updates (e.g. cart badge counter or mini ticker) without touching the rest of the page. |
| router.refresh() | Client Component (Browser) | Entire active page | When a client action needs fresh server props for the whole page without losing client state or scrolling to top. |
Redirection: Which redirection strategy should you use?
| Strategy | Context / Location | HTTP / Browser Mechanism | When to Choose It |
|---|---|---|---|
| redirect(path) in getProps | Server (page_functions.ts) | Real HTTP 307 Response | Fastest & cleanest: Auth guards, permission checks, or missing data redirects executed before any HTML or component rendering begins. |
| redirect(path) in Component | Universal (Server or Client) | HTTP 307 if headers unsent; SPA navigation if stream started | When redirection criteria depend on intermediate component tree logic. |
| <ClientRedirect to="..." /> | Client Component (JSX render) | Client-side router push/replace | Declarative fallback rendering in client tabs, wizard step redirections, or empty states. |
| router.replace(url) | Client Event Handler | History replace without entry | Post-submission redirect where clicking browser "Back" should not re-submit the action (e.g. login form, payment checkout). |
Route Parameter Access: Where should you read route data?
| Access Pattern | Environment | Return Type | When to Choose It |
|---|---|---|---|
| params in page.tsx (PageProps) | Universal (Server or Client) | RouteParams<Pattern> | Directly rendering route tokens in the page view (e.g. <h1>Product #{params.id}</h1>) with compile-time type validation. |
| params in layout.tsx (LayoutProps) | Universal (Server or Client) | RouteParams<Pattern> | Shared navigation headers, dynamic breadcrumbs, or sidebars that wrap child segments for that parameter. |
| params in getProps(params) | Server Only (page_functions.ts) | RouteParams<Pattern> | Fetching database records or querying external APIs based on dynamic route IDs before rendering. |
| params in not_found.tsx (PageProps) | Universal (Server or Client) | RouteParams<Pattern> | Scoped 404 views displaying the missing item ID (e.g. Item "{params.slug}" not found). |
| params in error.tsx (ErrorProps) | Universal (Server or Client) | RouteParams<Pattern> | Scoped 500 error pages showing diagnostic context or retry options for that specific resource. |
| usePathname() | Universal (Server or Client) | string | Navigation bars, sidebars, or layout components that need to detect the current URL path without relying on child props. |
| useSearchParams() | Universal (Server or Client) | ReadonlyURLSearchParams | Reading query string parameters (filters, pagination, search keywords) in either server or client components. |