Configuration & Plugins

2.1 Esbuild Pre-Bundling & Native Path Aliases

When Dinou loads dinou.config.js or dinou.config.ts, it automatically bundles the configuration file on the fly using Esbuild (<20ms) before execution:

• Native tsconfig.json Path Aliases: You can freely import shared models, utilities, or plugin factories using path aliases (e.g. import { authPlugin } from "@/server/plugins/auth";) without encountering Node's runtime ERR_MODULE_NOT_FOUND.
• First-Class TypeScript Support: You can author your configuration in dinou.config.ts without installing extra transpilers or ts-node runners.
• External Dependencies: All third-party packages (such as ioredis, socket.io, stripe) remain clean external references.

3.1 Global Partial Prerendering (ppr)

Dinou introduces first-class Partial Prerendering (PPR). When ppr: true is configured globally in dinou.config.js:

• All static-eligible routes pre-render an instant static HTML shell at build/ISR time.
• Dynamic components wrapped in React <Suspense> leave streaming placeholder holes that resume and stream from the server upon request.

// dinou.config.js
export default defineConfig({
  ppr: true, // Enables Partial Prerendering across all eligible routes
});

You can override PPR on a per-route or per-layout basis inside page_functions.ts or layout_functions.ts by exporting export const ppr = false;.

3.2 React StrictMode (reactStrictMode)

In Dinou, reactStrictMode defaults to true. When active in development mode, React intentionally invokes components and effects twice to identify unintended side effects and ensure strict compliance with the React Compiler.

// dinou.config.js
export default defineConfig({
  // Enabled by default (recommended). Set to false to disable:
  reactStrictMode: false,
});

3.3 Storage Adapter (storage)

Dinou's ISR and ISG caching engine uses a pluggable storage adapter. By default, Dinou uses the local filesystem (in Node.js/Bun) or Deno KV (in Deno). You can supply a custom storage adapter (such as Redis or Cloudflare KV) in dinou.config.js:

// dinou.config.js
import { RedisStorage } from "dinou/server";
import Redis from "ioredis";

export default defineConfig({
  storage: new RedisStorage(new Redis(process.env.REDIS_URL)),
});

3.4 Universal Setup Files (setupFiles)

An array of file paths to execute before any application code runs. Injected at Line 1 of every compilation stage across all target runtimes via Esbuild's native inject mechanism.

// dinou.config.js
export default defineConfig({
  // Global polyfills or early APM initialization (e.g. Sentry, Datadog)
  setupFiles: ["./src/polyfills.ts"],
});

3.5 Plugins Array (plugins)

An array of plugin objects conforming to the DinouPlugin interface, executed sequentially on every incoming request.

5.1 Context Parameters: { server, isDev, use }

The hook receives a single context object:

export interface ServerHookContext {
  /** The native Node.js HTTP/HTTPS server instance */
  server: http.Server | https.Server;

  /** Boolean indicating whether the server is running in development mode (dinou dev) */
  isDev: boolean;

  /** Registers a low-level Node.js HTTP middleware (req, res, next) before Dinou route handlers */
  use: (middleware: NodeMiddleware) => void;
}

5.2 The Node Middleware Pipeline (use)

Middlewares registered via use adopt the standard Node.js middleware signature (req, res, next) (compatible with utilities like cors or helmet):

type NodeMiddleware = (
  req: http.IncomingMessage,
  res: http.ServerResponse,
  next: () => void
) => void | Promise<void>;

When a request arrives at the Node server, Dinou passes req and res through each registered middleware. The middleware can:

• Call next(): Hand off control to the next middleware in line, and ultimately to Dinou's page routing and React SSR engine.
• Omit calling next() (Short-Circuit): If an external library (like Socket.IO) handles the HTTP request, return without calling next(). Dinou bypasses page routing and will not produce a 404 error.
• Send Response via res.end(): For Kubernetes health checks (/healthz) or Prometheus metrics (/metrics), write headers and send the response directly. Dinou detects that headers were sent and halts the pipeline immediately with zero rendering overhead.

5.3 configureServer vs. onRequest Decision Matrix

Choose the appropriate plugin hook based on the runtime requirements of your task:

6.1 The context Object (RequestContextStore)

The context parameter provides access to parsed request metadata, response mutation helpers, platform edge bindings, and custom shared state:

export interface RequestContextStore {
  /** Parsed incoming request metadata */
  req: {
    path: string;                    // Normalized URL pathname (e.g. "/admin/settings")
    method: string;                  // HTTP method ("GET", "POST", etc.)
    cookies: Record<string, string>; // Parsed cookie key-value pairs
    headers: Record<string, string>; // Lowercased incoming HTTP headers
    query: Record<string, string>;   // Parsed URL search parameters
    env?: Record<string, any>;       // Platform environment bindings
    ctx?: any;                       // Platform execution context
  };

  /** Outgoing response mutation helpers */
  res: {
    cookie(name: string, value: string, options?: CookieOptions): void;
    clearCookie(name: string, options?: CookieOptions): void;
    setHeader(name: string, value: string): void;
    status(code: number): void;
    redirect(url: string): void;
    redirect(status: number, url: string): void;
  };

  /** Direct platform bindings (Cloudflare Workers KV, D1, R2, etc.) */
  env?: Record<string, any>;

  /** Platform runtime context (e.g. ctx.waitUntil for background execution) */
  ctx?: { waitUntil(promise: Promise<any>): void };

  /** Custom state attached by plugins (context.user, context.session, etc.) */
  [key: string]: any;
}

6.2 Pattern 1: Short-Circuit & Webhooks (Returning Response)

If onRequest returns a Web Response instance, Dinou immediately returns that response to the client and aborts further processing. React Server Component rendering is completely bypassed:

const apiProbePlugin = {
  name: "api-probe",
  onRequest(request) {
    const url = new URL(request.url);
    if (url.pathname === "/api/ping") {
      return Response.json({ status: "pong", timestamp: Date.now() });
    }
  },
};

6.3 Pattern 2: Middleware & Context Mutation (getContext)

If onRequest returns void (or undefined), request processing continues normally. Any property attached to context is preserved in AsyncLocalStorage and becomes accessible in any server-side module:

const userSessionPlugin = {
  name: "user-session",
  async onRequest(request, context) {
    const sessionCookie = context.req.cookies["session_id"];
    if (sessionCookie) {
      // Validate session and attach user object
      const user = await validateSession(sessionCookie);
      context.user = user;
    }
  },
};

6.4 Context Sharing with Server Functions

When a client invokes a Server Function, Dinou:

1. Executes all registered plugin onRequest hooks for the incoming RPC request.
2. Instantiates the isolated Server Function execution context.
3. Automatically copies all custom properties from the root context to the action context.

This means any authentication claims, multi-tenant IDs, or shared services attached during onRequest are immediately accessible inside "use server" actions via getContext():

// src/actions/update-profile.ts
"use server";

import { getContext } from "dinou";

export async function updateProfile(formData: FormData) {
  const { user } = getContext();

  if (!user) {
    throw new Error("Unauthorized");
  }

  // user is cryptographically verified from the plugin onRequest hook
  await db.user.update({ where: { id: user.id }, data: { name: formData.get("name") } });
}

8.1 Resolution & Precedence Hierarchy

Dinou resolves setup files using an unambiguous hierarchy:

1. 1. Plugin Setup Files (plugin.setupFiles: string[]): Run first. Allows infrastructure plugins (APM, distributed tracing, metrics) to initialize before user code.
2. 2. Explicit User Config (config.setupFiles: string[]): Defined in dinou.config.js. When specified, this completely replaces any zero-config convention files.
3. 3. Zero-Config Convention: If config.setupFiles is omitted, Dinou automatically checks for ./dinou.setup.js or ./dinou.setup.ts strictly in the project root directory.

8.2 Environment Polyfills Recipe (DOMMatrix / Geometry)

To polyfill W3C geometry interfaces (required by pdfjs-dist) in headless Node, Bun, and standalone compiled binaries without native C++ compilation:

// dinou.setup.js (Project Root)
import { DOMMatrix, DOMPoint, DOMRect } from "@napi-rs/canvas/geometry.js";

// 1. W3C Geometry Interfaces (Pure JS, zero C++ native compilation bindings)
if (typeof globalThis.DOMMatrix === "undefined") {
  globalThis.DOMMatrix = DOMMatrix;
  globalThis.DOMPoint = DOMPoint;
  globalThis.DOMRect = DOMRect;
}

// 2. Minimal stubs for headless server environments
if (typeof globalThis.ImageData === "undefined") {
  globalThis.ImageData = class ImageData {
    constructor(width, height) {
      this.width = width;
      this.height = height;
      this.data = new Uint8ClampedArray(width * height * 4);
    }
  };
}