Dinou docs

Key File Location: ./dinou/core/generating-isg.js

💡 Overview

Incremental Static Generation (ISG) resolves a classic scaling dilemma: if your application contains thousands or millions of dynamic paths (such as product detail pages), rendering all of them upfront would lead to significant delay and resource consumption.

To optimize this, during production server startup, Dinou evaluates which routes should be static. For routes with dynamic segments (e.g., /posts/[id]), it pre-compiles only the paths explicitly returned by the route's getStaticPaths() function. For all other un-precompiled paths, the server executes generating-isg.js on their first request. This dynamic compiler evaluates the route, creates the static cache files (both RSC and HTML) on disk, and promotes the route to static so that subsequent visits bypass rendering entirely.

📊 Compilation Lifecycle

Below is the lifecycle of an incoming request on a non-compiled path:

🚀 Lazy Static Promotion

When the Express routing middleware intercepts a request and detects that the route exists in your dynamic files (e.g. src/posts/[id]/page.tsx) but has no pre-compiled index in the dist2/ cache, it triggers the ISG thread:

Bailout Checking: The engine renders the component tree. If the page is marked as dynamic (e.g., calls cookies()), it sets isDynamicFromServer.value = true and exits. The server continues to render this path dynamically.
Cache Promotion: If the run completes without bailouts, the engine compiles the RSC stream and HTML document. Once successfully saved to disk, subsequent page views bypass the React compiler entirely and are served as static files by Express.

🔒 Mutex Sharing & Lock Pools

To save resources and avoid race conditions, the ISG engine does not maintain its own lock pool.

Instead, it shares the exact same Set lock registry imported from revalidating.js:

const { regenerating } = require("./revalidating");

This ensures that if a background ISR task is already updating a page, the ISG thread cannot attempt to create a parallel compilation task for the same path, and vice versa.

🎯 Invocation & Conditionals (Where is it called?)

The generatingISG function is imported and called by the main web server (core/server.js) during the handling of wildcard page requests (/*).

To avoid slowing down the active user's request, the server executes the compilation as a "fire-and-forget" background task. It waits until the response has successfully finished streaming to the client (listening to Express's res.on("finish")) and then checks these conditions:

Production Only (!isDevelopment): ISG cache files are only compiled and served in production mode.
Success Status (res.statusCode === 200): Only promotes the page if it rendered successfully without crashes.
HTTP GET Method (req.method === "GET"): Only triggers compilation on standard GET navigations.
Server Ready (isReady): Verifies that the initial startup SSG generation of crawled routes has completed.

// Inside core/server.js wildcard route handler:
res.on("finish", () => {
  if (
    !isDevelopment &&
    res.statusCode === 200 &&
    req.method === "GET" &&
    isReady
  ) {
    generatingISG(reqPath, dynamicState); // Triggers background compile
  }
});

⚙️ Complete Code Walkthrough

Below is the full, complete code of generating-isg.js: