Nitro Server Engine

The Nitro Renderer is a special catch-all handler that intercepts all routes that do not match any specific API or route handler. It is primarily used for:

• Server-Side Rendering (SSR)
• Serving Single-Page Applications (SPAs)
• Creating custom HTML responses

Priority and Routing

The renderer acts as a catch-all route (/**) and has the lowest priority in the routing hierarchy:

1. Specific API routes (e.g., /api/users) are matched first.
2. Specific server routes (e.g., /about) are matched second.
3. The Renderer catches everything else.

WARNING

If you define a catch-all route (e.g., [...].ts) in your routes, Nitro will warn you that the renderer will override it. Use more specific routes or different HTTP methods to avoid conflicts.

A server entry is a special handler in Nitro that acts as a global middleware, running for every incoming request before routes are matched. It is ideal for cross-cutting concerns such as authentication, logging, request preprocessing, or custom routing logic.

Key Behaviors

• Termination: If the server entry returns a Response, the request lifecycle stops there.
• Continuation: If the server entry returns undefined (or nothing), the request continues to the next stage in the lifecycle (either a specific route handler or the renderer).
• Priority: Specific routes (in routes/) take priority. The server entry runs for unmatched routes before they reach the renderer.

export default {
  async fetch(req: Request) {
    // If you return a Response, the request stops here
    // If you return nothing, it continues to routes/ or the renderer
  }
}

The server entry is part of the request lifecycle, specifically acting as a catch-all handler for unmatched routes. The order of execution is:

1. Server hook: request
2. Route rules: Headers, redirects, etc.
3. Global middleware: Files in the middleware/ directory.
4. Route matching:
   • Specific routes: Handlers in routes/ (if matched, they handle the request).
   • Server entry: Runs for unmatched routes.
   • Renderer: renderer.ts or index.html (if no response was returned by the server entry).

Nitro allows you to provide overrides for specific environments using $development and $production keys. The environment is identified as "development" during nitro dev and "production" during nitro build.

import { defineConfig } from "nitro";

export default defineConfig({
  logLevel: 3,
  $development: {
    // Options applied only in development mode
    debug: true,
  },
  $production: {
    // Options applied only in production builds
    minify: true,
  },
})

Nitro allows you to override any key defined in your runtimeConfig schema using environment variables. To do this, prefix the environment variable name with NITRO_ followed by the config key in uppercase. For example, a config key apiKey is overridden by NITRO_API_KEY.

# Example .env file
NITRO_API_KEY=secret-api-key

Nitro distinguishes between two types of assets:

1. Public Assets: Files in the public/ directory that are served directly to the browser (e.g., images, robots.txt). They are accessible via URL paths.
2. Server Assets: Files in the assets/ directory that are bundled into the server for programmatic access via the useStorage() API. These are intended for server-side logic rather than direct client access.

Use Public Assets for anything the client needs to download. Use Server Assets for data or templates needed by your server handlers. For large files, prefer Server Assets or external storage to avoid bloating the server bundle.

In a Vite + Nitro SSR setup, the <!--ssr-outlet--> comment in your index.html acts as a injection point.

When a request is made, Nitro executes the fetch method defined in your server entry. The return value of that fetch method (which can be a string or a ReadableStream) is then used to replace the <!--ssr-outlet--> placeholder in the HTML template before the final response is sent to the client.

To leverage multi-core systems and improve performance, use the node_cluster preset. This mode spawns multiple workers to handle incoming requests.

### Cluster Configuration
- `NITRO_CLUSTER_WORKERS`: Number of cluster workers to spawn. Defaults to the number of available CPU cores.

Note: This preset supports all environment variables available to the `node_server` preset.