nitro 3.0.1-alpha.2 → 3.0.260415-beta

package/dist/docs/0.docs/15.migration.md

@@ -0,0 +1,213 @@
+# Migration Guide
+
+> [!NOTE]
+> This is a living document for migrating from Nitro 2 to 3. Please check it regularly while using the beta version.
+
+Nitro v3 introduces intentional backward-incompatible changes. This guide helps you migrate from Nitro v2.
+
+## `nitropack` is renamed to `nitro`
+
+The NPM package [nitropack](https://www.npmjs.com/package/nitropack) (v2) has been renamed to [nitro](https://www.npmjs.com/package/nitro) (v3).
+
+**Migration:** Update the `nitropack` dependency to `nitro` in `package.json`:
+
+```diff [release channel]
+{
+  "dependencies": {
+--    "nitropack": "latest"
+++    "nitro": "latest"
+  }
+}
+```
+
+```diff [nightly channel]
+{
+  "dependencies": {
+--    "nitropack": "latest"
+++    "nitro": "npm:nitro-nightly"
+  }
+}
+```
+
+**Migration:** Search your codebase and rename all instances of nitropack to nitro:
+
+```diff
+-- import { defineNitroConfig } from "nitropack/config"
+++ import { defineConfig } from "nitro"
+```
+
+## nitro/runtime
+
+Runtime utils had been moved to individual `nitro/*` subpath exports. Refer to docs for usage.
+
+```diff
+-- import { useStorage } from "nitropack/runtime/storage"
+++ import { useStorage } from "nitro/storage"
+```
+
+## Minimum Supported Node.js Version: 20
+
+Nitro now requires a minimum Node.js version of 20, as Node.js 18 reaches end-of-life in [April 2025](https://nodejs.org/en/about/previous-releases).
+
+Please upgrade to the [latest LTS](https://nodejs.org/en/download) version (>= 20).
+
+**Migration:**
+
+- Check your local Node.js version using `node --version` and update if necessary.
+- If you use a CI/CD system for deployment, ensure that your pipeline is running Node.js 20 or higher.
+- If your hosting provider manages the Node.js runtime, make sure it's set to version 20, 22, or later.
+
+## Type Imports
+Nitro types are now only exported from `nitro/types`.
+
+**Migration:** Import types from nitro/types instead of nitro:
+
+```diff
+-- import { NitroRuntimeConfig } from "nitropack"
+++ import { NitroRuntimeConfig } from "nitro/types"
+```
+
+## App Config Support Removed
+
+Nitro v2 supported a bundled app config that allowed defining configurations in `app.config.ts` and accessing them at runtime via `useAppConfig()`.
+
+This feature had been removed.
+
+**Migration:**
+
+Use a regular `.ts` file in your server directory and import it directly.
+
+## Preset updates
+
+Nitro presets have been updated for the latest compatibility.
+
+Some (legacy) presets have been removed or renamed.
+
+| Old Preset | New Preset |
+| --- | --- |
+| `node` | `node_middleware` (export changed to `middleware`) |
+| `cloudflare`, `cloudflare_worker`, `cloudflare_module_legacy` | `cloudflare_module` |
+| `deno-server-legacy` | `deno_server` with Deno v2 |
+| `netlify-builder` | `netlify` or `netlify_edge` |
+| `vercel-edge` | `vercel` with Fluid compute enabled |
+| `azure`, `azure_functions` | `azure_swa` |
+| `firebase` | `firebase_app_hosting` |
+| `iis` | `iis_handler` |
+| `deno` | `deno_deploy` |
+| `edgio` | Discontinued |
+| `cli` | Removed due to lack of use |
+| `service_worker` | Removed due to instability |
+
+## Cloudflare Bindings Access
+
+In Nitro v2, Cloudflare environment variables and bindings were accessible via `event.context.cloudflare.env`.
+
+In Nitro v3, the Cloudflare runtime context is attached to the request's runtime object instead.
+
+**Migration:**
+
+```diff
+-- const { cloudflare } = event.context
+-- const binding = cloudflare.env.MY_BINDING
+++ const { env } = event.req.runtime.cloudflare
+++ const binding = env.MY_BINDING
+```
+
+## Changed nitro subpath imports
+
+Nitro v2 introduced multiple subpath exports, some of which have been removed or updated:
+
+- `nitro/rollup`, `nitropack/core` (use `nitro/builder`)
+- `nitropack/runtime/*` (use `nitro/*`)
+- `nitropack/kit` (removed)
+- `nitropack/presets` (removed)
+An experimental `nitropack/kit` was introduced but has now been removed. A standalone Nitro Kit package may be introduced in the future with clearer objectives.
+
+**Migration:**
+
+- Use `NitroModule` from `nitro/types` instead of `defineNitroModule` from the kit.
+- Prefer built-in Nitro presets (external presets are only for evaluation purposes).
+
+## H3 v2
+Nitro v3 upgrades to [H3 v2](https://h3.dev), which includes API changes. All H3 utilities are imported from `nitro/h3`.
+
+### Web Standards
+
+H3 v2 is rewritten based on web standard primitives ([`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL), [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers), [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request), and [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)).
+
+Access to `event.node.{req,res}` is only available in Node.js runtime. `event.web` is renamed to `event.req` (instance of web [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)).
+
+### Response Handling
+
+You should always explicitly **return** the response body or **throw** an error:
+
+```diff
+-- import { send, sendRedirect, sendStream } from "nitro/h3"
+-- send(event, value)
+-- sendStream(event, stream)
+-- sendRedirect(event, location, code)
+++ import { redirect } from "nitro/h3"
+++ return value
+++ return stream
+++ return redirect(event, location, code)
+```
+
+Other changes:
+
+- `sendError(event, error)` → `throw createError(error)`
+- `sendNoContent(event)` → `return noContent(event)`
+- `sendProxy(event, target)` → `return proxy(event, target)`
+
+### Request Body
+Most body utilities can be replaced with native `event.req` methods:
+
+```diff
+-- import { readBody, readRawBody, readFormData } from "nitro/h3"
+++ // Use native Request methods
+++ const json = await event.req.json()
+++ const text = await event.req.text()
+++ const formData = await event.req.formData()
+++ const stream = event.req.body
+```
+
+### Headers
+
+H3 now uses standard web [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers). Header values are always plain `string` (no `null`, `undefined`, or `string[]`).
+
+```diff
+-- import { getHeader, setHeader, getResponseStatus } from "nitro/h3"
+-- getHeader(event, "x-foo")
+-- setHeader(event, "x-foo", "bar")
+++ event.req.headers.get("x-foo")
+++ event.res.headers.set("x-foo", "bar")
+++ event.res.status // instead of getResponseStatus(event)
+```
+
+### Handler Utils
+
+```diff
+-- import { eventHandler, defineEventHandler } from "nitro/h3"
+++ import { defineHandler } from "nitro"
+```
+
+- `lazyEventHandler` → `defineLazyEventHandler`
+- `useBase` → `withBase`
+
+### Error Utils
+
+```diff
+-- import { createError, isError } from "nitro/h3"
+++ import { HTTPError } from "nitro"
+++ throw new HTTPError({ status: 404, message: "Not found" })
+++ HTTPError.isError(error)
+```
+
+### Node.js Utils
+
+```diff
+-- import { defineNodeListener, fromNodeMiddleware, toNodeListener } from "nitro/h3"
+++ import { defineNodeHandler, fromNodeHandler, toNodeHandler } from "nitro/h3"
+```
+
+## Optional Hooks
+If you were using `useNitroApp().hooks` outside of Nitro plugins before, it might be undefined. Use new `useNitroHooks()` to guarantee having an instance.

package/dist/docs/0.docs/16.nightly.md

@@ -0,0 +1,31 @@
+# Nightly Channel
+
+> Nitro has a nightly release channel that automatically releases for every commit to `main` branch to try latest changes.
+
+You can opt-in to the nightly release channel by updating your `package.json`:
+
+```json
+{
+  "devDependencies": {
+    "nitro": "npm:nitro-nightly@latest"
+  }
+}
+```
+
+Remove the lockfile (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock`, or `bun.lockb`) and reinstall the dependencies.
+
+<important>
+
+When using **Bun as package manager** in a mono-repo, you need to make sure nitro package is properly hoisted.
+
+```toml [bunfig.toml]
+[install]
+publicHoistPattern = ["nitro*"]
+```
+</important>
+
+<important>
+
+Avoid using `<npm|pnpm|yarn|bun|deno> install nitro-nightly`; it does not install correctly.
+If you encounter issues, delete your `node_modules` and lock files, then follow the steps above.
+</important>

package/dist/docs/0.docs/2.renderer.md

@@ -0,0 +1,322 @@
+# 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.
+
+<code-group>
+
+```html [index.html]
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>My Vite + Nitro App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+
+```ts [routes/api/hello.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler((event) => {
+  return { hello: "API" };
+});
+```
+</code-group>
+
+<tip>
+
+When `index.html` is detected, Nitro will automatically log in the terminal: `Using index.html as renderer template.`
+</tip>
+
+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.
+
+<code-group>
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  renderer: {
+    template: './app.html'
+  }
+})
+```
+
+```html [app.html]
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Custom Template</title>
+  </head>
+  <body>
+    <div id="root">Loading...</div>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>
+```
+</code-group>
+
+### 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 `<?= expression ?>` — raw (unescaped) output
+
+```html
+<h1>Hello {{ $URL.pathname }}</h1>
+<div>{{{ '<strong>raw html</strong>' }}}</div>
+```
+
+#### Control flow
+Use `<? ... ?>` for JavaScript control flow:
+
+```html
+<? if ($METHOD === 'POST') { ?>
+  <p>Form submitted!</p>
+<? } else { ?>
+  <form method="POST">
+    <button type="submit">Submit</button>
+  </form>
+<? } ?>
+
+<ul>
+<? for (const item of ['a', 'b', 'c']) { ?>
+  <li>{{ item }}</li>
+<? } ?>
+</ul>
+```
+
+#### Server scripts
+
+Use `<script server>` to execute JavaScript on the server:
+
+```html
+<script server>
+  const data = await fetch('https://api.example.com/data').then(r => r.json());
+</script>
+<pre>{{ JSON.stringify(data) }}</pre>
+```
+
+#### Streaming content
+
+Use the `echo()` function for streaming content. It accepts strings, functions, Promises, Response objects, or ReadableStreams:
+
+```html
+<script server>
+  echo("Loading...");
+  echo(async () => fetch("https://api.example.com/data"));
+</script>
+```
+
+#### 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]
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Dynamic template</title>
+  </head>
+  <body>
+    <h1>Hello {{ $REQUEST.url }}</h1>
+    <p>Welcome, <?= $COOKIES["user"] || "Guest" ?>!</p>
+    <script server>
+      setCookie("visited", "true", { maxAge: 3600 });
+    </script>
+  </body>
+</html>
+```
+
+<read-more></read-more>
+
+## 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 */ `<!DOCTYPE html>
+    <html>
+    <head>
+      <title>Custom Renderer</title>
+    </head>
+    <body>
+      <h1>Hello from custom renderer!</h1>
+      <p>Current path: ${url.pathname}</p>
+    </body>
+    </html>`,
+    { 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'
+  }
+})
+```
+
+<note>
+
+When `renderer.handler` is set, it takes full control of rendering. The `renderer.template` option is ignored.
+</note>
+
+## 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)
+```
+
+<warning>
+
+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.
+</warning>
+
+<read-more></read-more>
+
+## 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 `<!--ssr-outlet-->`
+
+When using Vite environments with an `ssr` service, you can add an `<!--ssr-outlet-->` comment to your `index.html`. Nitro will replace it with the output from your SSR entry during rendering:
+
+```html [index.html]
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>SSR App</title>
+  </head>
+  <body>
+    <div id="app"><!--ssr-outlet--></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+
+### 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.