# Nitro Renderer
> Use a renderer to handle all unmatched routes with custom HTML or a templating system.
The renderer is a special handler in Nitro that catches all routes that don't match any specific API or route handler. It's commonly used for server-side rendering (SSR), serving single-page applications (SPAs), or creating custom HTML responses.
## Configuration
The renderer is configured using the `renderer` option in your Nitro config:
```ts [nitro.config.ts]
import { defineConfig } from "nitro";
export default defineConfig({
renderer: {
template: './index.html', // Path to HTML template file
handler: './renderer.ts', // Path to custom renderer handler
static: false, // Treat template as static HTML (no rendu processing)
}
})
```
| Option | Type | Description |
| --- | --- | --- |
| `template` | `string` | Path to an HTML file used as the renderer template. |
| `handler` | `string` | Path to a custom renderer handler module. |
| `static` | `boolean` | When `true`, skips rendu template processing and serves the HTML as-is. Auto-detected based on template syntax when not set. |
Set `renderer: false` in the config to explicitly disable the renderer entirely (including auto-detection of `index.html`).
## HTML template
### Auto-detected `index.html`
By default, Nitro automatically looks for an `index.html` file in your project src dir.
If found, Nitro will use it as the renderer template and serve it for all unmatched routes.
```html [index.html]
My Vite + Nitro App
```
```ts [routes/api/hello.ts]
import { defineHandler } from "nitro";
export default defineHandler((event) => {
return { hello: "API" };
});
```
When `index.html` is detected, Nitro will automatically log in the terminal: `Using index.html as renderer template.`
With this setup:
- `/api/hello` → Handled by your API routes
- `/about`, `/contact`, etc. → Served with `index.html`
### Custom HTML file
You can specify a custom HTML template file using the `renderer.template` option in your Nitro configuration.
```ts [nitro.config.ts]
import { defineConfig } from "nitro";
export default defineConfig({
renderer: {
template: './app.html'
}
})
```
```html [app.html]
Custom Template
Loading...
```
### Static templates
By default, Nitro auto-detects whether your HTML template contains [rendu](#hypertext-preprocessor-experimental) syntax. If it does, the template is processed dynamically on each request. If it doesn't, it's served as static HTML.
You can override this behavior with the `static` option:
```ts [nitro.config.ts]
import { defineConfig } from "nitro";
export default defineConfig({
renderer: {
template: './index.html',
static: true // Force static serving, skip template processing
}
})
```
In production, static templates are inlined into the server bundle and served directly for optimal performance.
### Hypertext Preprocessor (experimental)
Nitro uses [rendu](https://github.com/h3js/rendu) Hypertext Preprocessor, which provides a simple and powerful way to create dynamic HTML templates with JavaScript expressions.
#### Output expressions
- `{{ expression }}` — HTML-escaped output
- `{{{ expression }}}` or `` — raw (unescaped) output
```html
Hello {{ $URL.pathname }}
{{{ 'raw html' }}}
```
#### Control flow
Use `` for JavaScript control flow:
```html
Form submitted!
```
#### Server scripts
Use `
{{ JSON.stringify(data) }}
```
#### Streaming content
Use the `echo()` function for streaming content. It accepts strings, functions, Promises, Response objects, or ReadableStreams:
```html
```
#### Global variables
Access request context within templates:
| Variable | Description |
| --- | --- |
| `$REQUEST` | The incoming `Request` object |
| `$METHOD` | HTTP method (`GET`, `POST`, etc.) |
| `$URL` | Request `URL` object |
| `$HEADERS` | Request headers |
| `$RESPONSE` | Response configuration object |
| `$COOKIES` | Read-only object containing request cookies |
#### Built-in functions
| Function | Description |
| --- | --- |
| `htmlspecialchars(str)` | Escape HTML characters (automatically applied in `{{ }}` syntax) |
| `setCookie(name, value, options?)` | Set a cookie in the response |
| `redirect(url)` | Redirect the user to another URL |
| `echo(content)` | Stream content to the response |
```html [index.html]
Dynamic template
Hello {{ $REQUEST.url }}
Welcome, !
```
## Custom renderer handler
For more complex scenarios, you can create a custom renderer handler that programmatically generates responses.
The handler is a default export function that receives an H3 event object. You can access the incoming `Request` via `event.req`:
```ts [renderer.ts]
export default function renderer({ req }: { req: Request }) {
const url = new URL(req.url);
return new Response(
/* html */ `
Custom Renderer
Hello from custom renderer!
Current path: ${url.pathname}
`,
{ headers: { "content-type": "text/html; charset=utf-8" } }
);
}
```
Then, specify the renderer entry in the Nitro config:
```ts [nitro.config.ts]
import { defineConfig } from "nitro";
export default defineConfig({
renderer: {
handler: './renderer.ts'
}
})
```
When `renderer.handler` is set, it takes full control of rendering. The `renderer.template` option is ignored.
## Renderer priority
The renderer always acts as a catch-all route (`/**`) and has the **lowest priority**. This means:
1. Specific API routes are matched first (e.g., `/api/users`)
2. Specific server routes are matched next (e.g., `/about`)
3. The renderer catches everything else
```md
api/
users.ts → /api/users (matched first)
routes/
about.ts → /about (matched second)
renderer.ts → /** (catches all other routes)
```
If you define a catch-all route (`[...].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.
## Vite integration
When using Nitro with Vite, the renderer integrates with Vite's build pipeline and dev server.
### Development mode
In development, the renderer template is read from disk on each request, so changes to `index.html` are reflected immediately without restarting the server. Vite's `transformIndexHtml` hook is applied to inject HMR client scripts and other dev-time transforms.
### SSR with ``
When using Vite environments with an `ssr` service, you can add an `` comment to your `index.html`. Nitro will replace it with the output from your SSR entry during rendering:
```html [index.html]
SSR App
```
### Production build
During production builds, Vite processes the `index.html` through its build pipeline (resolving scripts, CSS, and other assets), then Nitro inlines the transformed HTML into the server bundle.
## Use Cases
### Single-Page Application (SPA)
Serve your SPA's `index.html` for all routes to enable client-side routing:
> [!TIP]
> This is the default behavior of Nitro when used with Vite.