Dinou logoDinou
docs v5
npmGitHub

Migration & Changes from v4

Dinou v5 introduces a major internal rendering architecture redesign and loosens Server Component constraints to align more closely with native React behavior.

1. Architectural Refactor: Transition to React Flight

Dinou v5 completely overhauls the internal communication layer used during initial Server-Side Rendering (SSR).

In Dinou v4
During SSR, the parent process executed the Server Components and serialized the resulting resolved JSX tree into a custom JSON format to pass it to the child process. The child process then deserialized this JSON back into JSX before generating the HTML.
In Dinou v5
The custom JSON bridge between processes is completely removed. During SSR, the parent process streams the standard React Flight payload directly to the child process, which consumes it using createFromNodeStream to render the HTML.
Why this Refactor?
  • Unified Protocol: Consolidates both initial SSR and client-side page transitions under a single, native React Flight streaming protocol, removing the need for a separate JSON-based bridge.
  • True Stream Processing: The child process can now parse and render HTML chunks incrementally as they arrive, rather than waiting for a full JSON payload to be fully generated and deserialized.
  • Improved Robustness: Eliminates the custom JSX-to-JSON serialization code, delegating all prop serialization (including complex nested structures or React references) directly to React's native, battle-tested engine.
Show Technical Details (for Ejected Code)

In an ejected Dinou v5 project, the React Flight rendering and IPC pipeline is implemented across the following modules in dinou/core/:

  • dinou/core/server.js: Serves as the main HTTP entry. When a page request arrives, it obtains the JSX tree (via get-jsx.js) and serializes it using renderToPipeableStream from @roggc/react-server-dom-esm/server.
  • dinou/core/render-html.js: Runs as a child process. It receives the streamed Flight payload from the parent process over the child process IPC, deserializes it using createFromNodeStream from @roggc/react-server-dom-esm/client, and pipe-renders it to HTML using ReactDOM's server renderer.

2. Synchronous Server Components

In previous versions of Dinou, all Server Components had to follow strict rules. In v5, constraints are lifted to provide more flexibility.

In Dinou v4

Every Server Component was strictly required to be declared as an async function, even if it did not perform asynchronous operations.

// v4: Force async even for static components
export default async function Page() {
  return <h1>Hello World</h1>;
}
In Dinou v5

This restriction has been removed. A Server Component only needs to be async if it uses await in its body. Synchronous components work natively.

// v5: Pure synchronous components are supported
export default function Page() {
  return <h1>Hello World</h1>;
}

3. New APIs in page_functions

Dinou introduces new optional exports inside the page_functions.ts (or .js) files to give you finer control over dynamic routes, parameter validation, and cache tagging:

validateParams(params)

Allows dynamic route parameters validation (e.g., checking UUID formats or numeric IDs) before serving the page. Returning false will instantly abort the request and respond with a 404, bypassing render engines and data fetching.

// Validate id parameters are strictly numeric
export function validateParams(params) {
  return typeof params.id === "string" && /^\d+$/.test(params.id);
}
allowISG()

Allows opting out of Incremental Static Generation (ISG). If it returns false, any dynamic path that was not generated at server startup (via getStaticPaths) will return a 404 response on the spot instead of generating on-demand.

// Disable on-demand generation; serve getStaticPaths ONLY
export function allowISG() {
  return false;
}
Show Technical Details (for Ejected Code)

In the ejected core, these control flags are processed inside the routing middleware in dinou/core/server.js:

  • Caching: The page functions are imported dynamically and cached inside pageFunctionsConfigCache to avoid redundant disk reads during production requests.
  • Request Interception: The Express route handler checks the parsed validateParams and allowISG configurations before calling the rendering child processes. If a block is triggered, it exits early with a 404.
getCacheTags(params)
v5.1.0+

Assigns custom static cache tags to the generated route page to enable granular cache purging and on-demand regeneration via revalidateTag.

// Assign cache tags to the static page cache
export async function getCacheTags(params) {
  return ["products", `product-${params.id}`];
}

4. Built-in Anti-Bot Shield (Express Middleware)

Dinou v5 introduces an integrated Anti-Bot Shield middleware inside server.js to protect applications using dynamic Incremental Static Generation (ISG).

If you are developing a route that matches these patterns (for instance, if you require a page ending in .php or using paths like wp-admin), the server will block it and return a 404 by default. You can adjust the botGarbagePatterns list in dinou/core/server.js if you need to bypass this protection for specific routes.

Show Technical Details (for Ejected Code)

In the ejected dinou/core/server.js, the bot shield is implemented as an Express middleware placed immediately after cookieParser() and before any dynamic route resolution logic.

5. Minor Adjustments for Legacy Imports (Isolated Cases)

Dinou v5 enforces modern ES Modules (ESM) resolution standards.

This is only necessary for non-compliant third-party code and does not affect the standard source code of your application.

6. On-Demand Revalidationv5.1.0+

Dinou v5.1.0 introduces native support for On-Demand Revalidation. This allows you to purge and regenerate the static page cache of individual pages on-demand without rebuilding the entire application.

1. Assign Cache Tags in page_functions

To tag static page cache files for granular invalidations, export a getCacheTags function (which can be sync or async) from your route's page_functions.ts file.

// src/products/[id]/page_functions.ts
export async function getCacheTags(params) {
  // Can perform async checks (e.g., query database or CMS)
  const product = await db.getProduct(params.id);
  return ["products", product.category, `product-${params.id}`];
}

2. Trigger Revalidation in Server Functions (Primary Use Case)

The primary and recommended way to trigger on-demand revalidation is inside Server Functions (Server Actions) immediately after performing database updates or data mutations. This ensures the static cache is instantly updated on the next request.

// src/actions/update-product.js
"use server";
import { revalidateTag } from "dinou/server";
import { db } from "@/db";

export async function updateProduct(productId, data) {
  // 1. Mutate the data in database
  await db.updateProduct(productId, data);

  // 2. Trigger on-demand revalidation on the server
  // This will purge and rebuild all static pages tagged with this ID
  await revalidateTag(`product-${productId}`);
}