+
+
+
+
+
+
+
+
+
+
+ + {{ feature.title }} +
++ {{ feature.description }} +
+ +
+
+
+
+
+
+
+
+
+
+
+
+ + + {{ headline || 'Performance' }} +
++ {{ title || 'Built for speed' }} +
+
+
+
+
+
+
+
+
+
+
+ {{ metric.value }}
+ {{ metric.unit }}
+
+
+ + {{ metric.label }} +
+ ++ {{ metric.description }} +
+ +
+
+
+
+
+
+
+
- 
-
+
-
+
Follow the instructions from the CLI and you will be ready to start your development server.
## Add to a Vite project
-To add Nitro to an existing Vite project, follow these instructions:
+You can add Nitro to any existing Vite project to get API routes, server-side rendering, and more.
::steps{level="3"}
-### Install `nitro` package
+### Install `nitro` and `vite`
-:pm-install{name="nitro"}
+:pm-install{name="nitro vite"}
-### Add Nitro plugin
+### Add Nitro plugin to Vite
-```js [vite.config.mjs] {2,6}
+Add the Nitro plugin to your `vite.config.ts`:
+
+```ts [vite.config.ts] {2,6}
import { defineConfig } from "vite";
import { nitro } from "nitro/vite";
@@ -62,13 +53,71 @@ export default defineConfig({
plugins: [
nitro()
],
- nitro: {
- serverDir: './'
- }
});
```
+### Configure Nitro
+
+Create a `nitro.config.ts` to configure the server directory:
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+ serverDir: "./server",
+});
+```
+
+The `serverDir` option tells Nitro where to look for your server routes. In this example, all routes will be inside the `server/` directory.
+
+### Create an API route
+
+Create your first API route at `server/api/test.ts`:
+
+::code-tree{defaultValue="server/api/test.ts"}
+```ts [server/api/test.ts]
+import { defineHandler } from "nitro/h3";
+
+export default defineHandler(() => {
+ return { message: "Hello Nitro!" };
+});
+```
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+ serverDir: "./server",
+});
+```
+```ts [vite.config.ts]
+import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
+
+export default defineConfig({
+ plugins: [nitro()],
+});
+```
+::
+
+The file path maps directly to the route URL — `server/api/test.ts` becomes `/api/test`.
+
+::tip
+As an alternative to filesystem routing, you can declare routes programmatically using the `routes` config option. See [Programmatic route handlers](/docs/routing#programmatic-route-handlers) for more details.
::
+::tip
+You can return strings, JSON objects, `Response` instances, or readable streams from your handlers. See [Routing](/docs/routing) for more about dynamic routes, methods, and middleware.
+::
+
+
+### Start the development server
+
+:pm-run{script="dev -- --open"}
+
+Your API route is now accessible at `http://localhost:3000/api/test` :sparkles:
+
+
+
+
+
-That's it, you can now add server and API routes to your Vite project!
diff --git a/docs/1.docs/4.renderer.md b/docs/1.docs/4.renderer.md
index 4dde09419b..2450c955b7 100644
--- a/docs/1.docs/4.renderer.md
+++ b/docs/1.docs/4.renderer.md
@@ -8,12 +8,32 @@ navigation:
> Use a renderer to handle all unmatched routes with custom HTML or a templating system.
-::warning
-Nitro v3 Alpha docs are a work in progress — expect updates, rough edges, and occasional inaccuracies.
-::
-
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 { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+ 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`
@@ -84,22 +104,102 @@ export default defineNitroConfig({
```
::
+### 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 { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+ 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.
-You can use special delimiters to inject dynamic content:
-- `{{ content }}` to output HTML-escaped content
-- `{{{ content }}}` or `` to output raw (unescaped) content
-- `` for JavaScript control flow
+#### Output expressions
+
+- `{{ expression }}` — HTML-escaped output
+- `{{{ expression }}}` or `` — raw (unescaped) output
+
+```html
+Preview
+
+
+
+
+ Hello {{ $URL.pathname }}
+{{{ 'raw html' }}}
+```
-It also exposes global variables:
-- `$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
+#### Control flow
+
+Use `` for JavaScript control flow:
+
+```html
+
+ Form submitted!
+ + + + +-
+
+
- {{ item }} + +
{{ 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]
@@ -110,6 +210,10 @@ It also exposes global variables:
Hello {{ $REQUEST.url }}
+Welcome, !
+