# Dinou v10 — Complete Technical Reference for LLMs
> Dinou is a Web Standards-native React 19 full-stack framework featuring a 0-fork Dual-Bundle in-memory engine, End-to-End Type-Safe Routing with contextual `"./dinou"` modules, 3D Layered Caching (Horizontal Layouts + Vertical `` Micro-ISR + Partial Prerendering), Tri-Bundler freedom (Esbuild, Rollup, Webpack), universal deployment (Node.js, Netlify Functions v2, Cloudflare Workers, Deno, Bun, native binaries, Static Export SPA), and 100% reversible `dinou eject` / `dinou uneject`.
- Website: https://dinou.dev
- Index: https://dinou.dev/llms.txt
- Peer requirements: `react >= 19.3.1`, `react-dom >= 19.3.1`, `"type": "module"` in `package.json`.
---
## 1. Critical Differences from Next.js (Read First)
| Topic | Dinou v10 | Common LLM Mistake to Avoid |
|---|---|---|
| Route root | `src/` (`src/page.tsx`, `src/layout.tsx`) | Do NOT use `app/` or `pages/`. |
| Route config & loaders | Sibling `page_functions.ts` / `layout_functions.ts` | Do NOT export `revalidate`, `generateStaticParams`, or `dynamic` from `page.tsx`. |
| Query parameters | `useSearchParams()` hook from `"dinou"` (works in RSC & Client) | Dinou does NOT pass a `searchParams` prop to `page.tsx`. |
| Dynamic vs Static | `revalidate = 0` (SSR), `>= 1` (ISR seconds), `false`/omitted (SSG) | Do NOT export `dynamic = "force-dynamic"` (removed in v7). |
| PPR inheritance | Strictly **per-segment** (falls back to `dinou.config.ts`) | `export const ppr = true` on a parent layout does NOT cascade to child pages. |
| Helper folders | Clean names: `src/components/`, `src/lib/`, `src/plugins/` | NEVER put active code in `src/_components/` or `src/_lib/`! `_folder` subtrees are completely excluded from bundlers and fail at compile time. |
| Public env vars | `DINOU_PUBLIC_*` prefix | Do NOT use `NEXT_PUBLIC_*` or `VITE_*`. |
| Server env vars | `getContext().env` (universal across all 5 runtimes + CF bindings) | Prefer `getContext().env` over top-level `process.env` for Edge/Cloudflare parity. |
| Middleware / APIs | `dinou.config.ts` plugins with `onRequest(request, context)` | Do NOT create `middleware.ts` or `route.ts`. Return a Web `Response` from `onRequest` to short-circuit API/webhook routes. |
| Navigation imports | `` and `useRouter()` from `"dinou"` or `"./dinou"` | Do NOT import from `"next/link"` or `"next/navigation"`. |
| Layout opt-out | Empty marker files `no_layout` or `reset_layout` in route folder | No special layout export needed. |
| 404 & Error files | `not_found.tsx` and `error.tsx` (snake_case `not_found`) | Note underscore in `not_found.tsx` (not `not-found.tsx`). |
---
## 2. Project Setup & `tsconfig.json`
```bash
npx create-dinou@latest my-app
cd my-app
npm run dev
```
Recommended `tsconfig.json`:
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "bundler",
"jsx": "react-jsx",
"strict": true,
"rootDirs": ["src", ".dinou/routes"],
"paths": {
"@/*": ["./src/*"]
}
},
"include": ["dinou-env.d.ts", ".dinou/types/**/*.d.ts", "src/**/*"]
}
```
Root `dinou-env.d.ts`:
```ts
///
```
---
## 3. File-System Routing (`src/`)
Every folder under `src/` containing a `page.{tsx,ts,jsx,js}` defines a URL route. Folders without `page.*` are ignored by the router (so `src/components/`, `src/lib/`, `src/plugins/` need no prefix).
### Reserved Route Files
- `page.tsx`: Route UI (Server Component by default; may be `"use client"`).
- `layout.tsx`: Persistent layout shell wrapping `{ children }` and sibling `@slot` props. Preserves client state across navigations (Horizontal Segmentation).
- `page_functions.ts` / `layout_functions.ts`: Server lifecycle hooks and caching config for that segment.
- `error.tsx`: Scoped error boundary (`{ error, params }`).
- `not_found.tsx`: Scoped 404 boundary (`{ params }`).
- `no_layout`: Extensionless marker file — disables all parent layouts for this route.
- `reset_layout`: Extensionless marker file — resets ancestor layouts and starts a new layout chain from this folder's `layout.tsx`.
### Folder Conventions & Specificity Precedence
1. Static segment: `src/blog/page.tsx` → `/blog` (highest precedence)
2. Required dynamic: `src/blog/[slug]/page.tsx` → `params: { slug: string }`
3. Optional dynamic: `src/shop/[[category]]/page.tsx` → `params: { category?: string }`
4. Catch-all: `src/docs/[...slug]/page.tsx` → `params: { slug: string[] }`
5. Optional catch-all: `src/files/[[...path]]/page.tsx` → runtime `params: { path: string[] }` (normalized to `[]` on `/files`; optional in `` and `getStaticPaths`)
6. Route groups: `src/(marketing)/about/page.tsx` → `/about` (omitted from URL)
7. Parallel slots: `src/dashboard/@analytics/page.tsx` → injected into `src/dashboard/layout.tsx` as prop `analytics: ReactNode` (supports nested sub-routes and `@slot/error.tsx`).
8. **Escaped / parked folders (`_folder`)**: Any `_`-prefixed directory under `src/` (`src/_archived/`, `src/blog/_drafts/`) is completely excluded from routing, bundlers, VFS, dev watchers, route types, and Server Functions (`403`). Importing from `src/_*` in active code fails at compile time. `_`-prefixed *files* inside active folders (e.g., `src/blog/_helper.ts`) remain valid.
---
## 4. End-to-End Type-Safe Routing & Contextual `"./dinou"`
Run `npx dinou typegen` (also runs automatically in `dinou dev` and `dinou build`) to emit:
- `.dinou/types/routes.d.ts`: All route, layout, `@slot`, error, and not-found parameter maps, plus `NodeJS.ProcessEnv` keys and custom `assetExtensions` module declarations.
- `.dinou/routes//dinou.{js,d.ts}`: Route-contextual virtual modules wired via `rootDirs: ["src", ".dinou/routes"]`.
### Zero-Boilerplate Contextual `"./dinou"` Usage
```tsx
// src/workspace/[org]/settings/page.tsx
import { Link, useRouter, ROUTE, type PageProps } from "./dinou";
export default function SettingsPage({ params }: PageProps) {
// params.org is automatically inferred as string (no manual route string)
// ROUTE === "/workspace/[org]/settings"
return (
{params.org} Settings
{/* Relative links autocomplete & validate without from="..." */}
Security
Members
{/* Dynamic pattern interpolation with compile-time validated params */}
Project 42
);
}
```
```tsx
// src/dashboard/layout.tsx (with sibling @sidebar and @metrics slots)
import type { LayoutProps } from "./dinou";
export default function DashboardLayout({ children, sidebar, metrics }: LayoutProps) {
return (
{metrics}{children}
);
}
```
```ts
// src/blog/[slug]/page_functions.ts
import type { PageFunctions } from "./dinou";
export const revalidate: PageFunctions["revalidate"] = 60;
export const getStaticPaths: PageFunctions["getStaticPaths"] = async () => ["hello-world"];
export const validateParams: PageFunctions["validateParams"] = (params) => Boolean(params?.slug);
export const getCacheTags: PageFunctions["getCacheTags"] = (params) => [`post:${params?.slug}`];
```
### Explicit Generic Imports from `"dinou"` (or `"dinou/server"`)
- `PageProps<"/blog/[slug]", CustomProps>`
- `LayoutProps<"/dashboard", CustomProps>` (auto-infers sibling `@slot` `ReactNode` props)
- `SlotProps<"/dashboard/@analytics">`
- `ErrorProps<"/blog/[slug]">`
- `NotFoundProps<"/blog/[slug]", CustomProps>`
- `PageFunctions<"/blog/[slug]", CustomProps>`
- `LayoutFunctions<"/[org]", CustomProps>`
- `RouteParams<"/blog/[slug]">`, `LayoutParams`, `SlotParams`, `ErrorParams`
- `DinouLinkTarget`, `DinouRoute`, `DinouRoutePattern`, `DinouFromRoute`
---
## 5. Navigation & Hooks (`"dinou"`)
- **``**: Type-safe SPA navigation with hover prefetching. Automatically yields to native browser behavior for external URLs, `target="_blank"`, `download`, or non-primary clicks. `fresh` bypasses client-side RSC memory cache.
- **`useRouter()`** (Client Component, referentially stable):
- `router.push(href, options?)` / `router.replace(href, options?)` — options accept `{ fresh?: boolean, params?: ..., from?: ... }`. For dynamic untyped strings from external SDKs, cast `to as DinouLinkTarget`.
- `router.back()` / `router.forward()`
- `router.refresh(options?)` — re-fetches active page RSC payload (pass `{ layout: true }` to also refresh active layout).
- **`usePathname()`**: Universal (Server + Client) hook returning current pathname without query string.
- **`useSearchParams()`**: Universal (Server + Client) hook returning `URLSearchParams`. Calling in a Server Component triggers Automatic Static Bailout (or registers a Dynamic PPR Hole inside `` on `ppr = true` routes). Calling in a Client Component does **not** cause false dynamic bailout on static/ISG/ISR/PPR routes.
- **`useNavigationLoading()`**: Client hook returning `boolean` while an SPA transition is pending.
- **`refreshSlot(slotId)`**: Client helper to refresh a single `` over RSC without reloading the page.
- **`redirect(destination)`**: Universal server redirect (`return redirect("/login")`). Sends HTTP `302` on hard navigation, `x-rsc-redirect` on SPA navigation, or `` after streaming begins. Works in Server Components, `getProps()`, and `layout_functions.ts`.
- **``**: Declarative client replacement redirect.
---
## 6. `page_functions.ts` & `layout_functions.ts` Contracts
All exports can be constants or sync/async functions (named exports take precedence over `export default`):
| Export | Type | Semantics |
|---|---|---|
| `revalidate` | `number \| false \| (() => ...)` | Single source of truth for rendering mode. `0` (or `< 1`) = Dynamic SSR on every request. `>= 1` = Static + ISR expiring after N **seconds** (SWR). `false` or omitted = Static forever (SSG/ISG) until on-demand revalidation. |
| `ppr` | `boolean \| (() => boolean \| Promise)` | Enables Partial Prerendering for **this segment only** (no parent-to-child inheritance). Falls back to `dinou.config.ts` `ppr` (`false` by default). |
| `allowISG` | `boolean \| (() => boolean \| Promise)` | Controls whether dynamic params absent from `getStaticPaths` can be generated on demand (`true` by default; falls back to `dinou.config.ts` `allowISG`). When `false`, ungenerated params return `404`. |
| `getProps` | `(params?) => Props \| Promise` | Optional server loader returning top-level props merged into `page.tsx` / `layout.tsx`. Primarily used when `page.tsx` is `"use client"`; Server Components can `await` directly without `getProps`. |
| `getStaticPaths` | `StaticPathItem[] \| (() => ...)` | Lists dynamic params to pre-render at build time (`["a", "b"]`, `[1, 2]`, `[["a", "b"]]`, `[undefined, "cat"]`, or `[{ slug: "a" }]`). Supported in both `page_functions.ts` and `layout_functions.ts`. |
| `validateParams` | `(params?) => boolean \| Promise` | Perimeter validator executed root-to-child before rendering or serving cached RSC. Returning `false` responds `404 Not Found`. |
| `getCacheTags` | `string[] \| ((params?) => string[] \| Promise)` | Associates cache tags for surgical `revalidateTag(tag)` invalidation. |
---
## 7. Rendering Modes, 3D Layered Caching & Streaming
1. **Static by Default (SSG)**: Routes without `revalidate = 0` and without dynamic server reads (`req.cookies`, `req.headers`, `req.query`, `useSearchParams()` in RSC) are pre-rendered at `npm run build` into `.dinou/dist2`.
2. **ISG & ISR**: Dynamic routes not in `getStaticPaths` generate and cache on first request (`allowISG = true`). With `revalidate = 60`, stale responses serve immediately while revalidating once in the background (TOCTOU-deduplicated).
3. **Dynamic SSR (`revalidate = 0` or Automatic Bailout)**: Runs on every request with **inline RSC streaming** (single server execution — zero duplicate fetches, zero `#418` hydration mismatches) and **progressive `` streaming** in production.
4. **Partial Prerendering (`export const ppr = true`)**:
- Build generates an instant static `shell.html` with `` markers (`ppr-hole-*`).
- Dynamic async Server Components, `useSearchParams()` in RSC, or Client Components receiving un-awaited `Promise` props inside `` stream live at request time.
- Call `noDynamic()` synchronously at the top of an async Server Component (before its first `await`) to bake its `` output into the static shell instead of making it a dynamic hole.
5. **3D Layered Segmentation**:
- **Horizontal**: `layout.tsx` + `layout_functions.ts` cache independently from child `page.tsx`.
- **Vertical (`` from `"dinou/server"`)**: Component-level Micro-ISR inside any page or layout.
```tsx
import { Suspense } from "react";
import { DinouCacheSlot, noDynamic } from "dinou/server";
export default function ProductPage({ params }: PageProps) {
return (
Loading recommendations...
}>
);
}
```
- Un-awaited `Promise` props passed from Server Components or `getProps()` to `"use client"` components inside `` are streamed intact over React Flight for React 19 `use(promise)` without blocking TTFB.
---
## 8. Server Functions (`"use server"`)
- Supported as **module-level** (`"use server"` at top of file, including `export default`) and **inline function-level** (`async function action() { "use server"; ... }` inside Server Components).
- Can be invoked directly from Client Components (`await createPost(...)`), bound to `