nitro 3.0.1-alpha.2 → 3.0.260415-beta

package/dist/docs/0.docs/10.lifecycle.md

@@ -0,0 +1,204 @@
+# Lifecycle
+
+> Understand how Nitro runs and serves incoming requests to your application.
+
+## Request lifecycle
+
+A request can be intercepted and terminated (with or without a response) from any of these layers, in this order:
+
+<steps>
+
+### `request` hook
+
+The `request` hook is the first code that runs for every incoming request. It is registered via a [server plugin](/docs/plugins):
+
+```ts [plugins/request-hook.ts]
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitroApp) => {
+  nitroApp.hooks.hook("request", (event) => {
+    console.log(`Incoming request on ${event.path}`);
+  });
+});
+```
+
+<note>
+
+Errors thrown inside the `request` hook are captured by the [`error` hook](#error-handling) and do not terminate the request pipeline.
+</note>
+
+### Static assets
+
+When static asset serving is enabled (the default for most presets), Nitro checks if the request matches a file in the `public/` directory **before** any other middleware or route handler runs.
+
+If a match is found, the static file is served immediately with appropriate `Content-Type`, `ETag`, `Last-Modified`, and `Cache-Control` headers. The request is terminated and no further middleware or routes are executed.
+
+Static assets also support content negotiation for pre-compressed files (gzip, brotli, zstd) via the `Accept-Encoding` header.
+
+### Route rules
+
+The matching route rules defined in the Nitro config will execute. Route rules run as middleware so most of them alter the response without terminating it (for instance, adding a header or setting a cache policy).
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  routeRules: {
+    '/**': { headers: { 'x-nitro': 'first' } }
+  }
+})
+```
+
+<read-more></read-more>
+
+### Global middleware
+
+Any global middleware defined in the `middleware/` directory will be run:
+
+```ts [middleware/info.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler((event) => {
+  event.context.info = { name: "Nitro" };
+});
+```
+
+<warning>
+
+Returning from a middleware will close the request and should be avoided when possible.
+</warning>
+
+<read-more>
+
+Learn more about Nitro middleware.
+</read-more>
+
+### Routed middleware
+
+Middleware that targets a specific route pattern (defined with a `route` in `middleware/`) runs after global middleware but before the matched route handler.
+
+### Routes
+
+Nitro will look at defined routes in the `routes/` folder to match the incoming request.
+
+```ts [routes/api/hello.ts]
+export default (event) => ({ world: true })
+```
+
+<read-more>
+
+Learn more about Nitro file-system routing.
+</read-more>
+
+If serverEntry is defined it will catch all requests not matching any other route acting as `/**` route handler.
+
+```ts [server.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler((event) => {
+  if (event.path === "/") {
+    return "Home page";
+  }
+});
+```
+
+<read-more>
+
+Learn more about Nitro server entry.
+</read-more>
+
+### Renderer
+
+If no route is matched, Nitro will look for a renderer handler (defined or auto-detected) to handle the request.
+
+<read-more>
+
+Learn more about Nitro renderer.
+</read-more>
+
+### `response` hook
+
+After the response is created (from any of the layers above), the `response` hook runs. This hook receives the final `Response` object and the event, and can be used to inspect or modify response headers:
+
+```ts [plugins/response-hook.ts]
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitroApp) => {
+  nitroApp.hooks.hook("response", (res, event) => {
+    console.log(`Response ${res.status} for ${event.path}`);
+  });
+});
+```
+
+<note>
+
+The `response` hook runs for every response, including static assets, middleware-terminated requests, and error responses.
+</note>
+</steps>
+
+## Error handling
+
+When an error occurs at any point in the request lifecycle, Nitro:
+
+1. Calls the `error` hook with the error and context (including the event and source tags).
+2. Passes the error to the **error handler** which converts it into an HTTP response.
+
+```ts [plugins/errors.ts]
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitroApp) => {
+  nitroApp.hooks.hook("error", (error, context) => {
+    console.error("Captured error:", error);
+    // context.event - the H3 event (if available)
+    // context.tags  - error source tags like "request", "response", "plugin"
+  });
+});
+```
+Errors are also tracked per-request in `event.req.context.nitro.errors` for inspection in later hooks.
+
+You can provide a custom error handler in the Nitro config to control error response formatting:
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  errorHandler: "~/error",
+})
+```
+
+Additionally, unhandled promise rejections and uncaught exceptions at the process level are automatically captured into the `error` hook with the tags `"unhandledRejection"` and `"uncaughtException"`.
+
+## Server shutdown
+
+When the Nitro server is shutting down, the `close` hook is called. Use this to clean up resources such as database connections, timers, or external service handles:
+
+```ts [plugins/cleanup.ts]
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitroApp) => {
+  nitroApp.hooks.hook("close", async () => {
+    // Clean up resources
+  });
+});
+```
+
+## Hooks reference
+
+All runtime hooks are registered through [server plugins](/docs/plugins) using `nitroApp.hooks.hook()`.
+
+| Hook | Signature | When it runs |
+| --- | --- | --- |
+| `request` | `(event: HTTPEvent) => void \| Promise<void>` | Start of each request, before routing. |
+| `response` | `(res: Response, event: HTTPEvent) => void \| Promise<void>` | After the response is created, before it is sent. |
+| `error` | `(error: Error, context: { event?, tags? }) => void` | When any error is captured during the lifecycle. |
+| `close` | `() => void` | When the Nitro server is shutting down. |
+
+<note>
+
+The `NitroRuntimeHooks` interface is augmentable. Deployment presets (such as Cloudflare) can extend it with platform-specific hooks.
+</note>
+
+<read-more>
+
+Learn more about Nitro plugins and hook usage examples.
+</read-more>

package/dist/docs/0.docs/11.openapi.md

@@ -0,0 +1,291 @@
+# OpenAPI
+
+> Nitro can automatically generate an [OpenAPI](https://www.openapis.org/) specification from your route handlers and serve interactive API documentation.
+
+Nitro scans all route handlers, extracts metadata defined with `defineRouteMeta`, and generates an [OpenAPI 3.1.0](https://spec.openapis.org/oas/v3.1.0) specification. Built-in UIs powered by [Scalar](https://scalar.com/) and [Swagger UI](https://swagger.io/tools/swagger-ui/) let you explore and test your API directly in the browser.
+
+> [!IMPORTANT]
+> OpenAPI support is currently experimental.
+
+## Enable OpenAPI
+
+Enable OpenAPI in your Nitro configuration:
+
+<code-group>
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  experimental: {
+    openAPI: true,
+  },
+});
+```
+</code-group>
+
+Once enabled, the following endpoints become available during development:
+
+| Endpoint | Description |
+| --- | --- |
+| `/_openapi.json` | OpenAPI 3.1.0 JSON specification |
+| `/_scalar` | Scalar API reference UI |
+| `/_swagger` | Swagger UI |
+
+## Route Metadata
+
+Use the `defineRouteMeta` macro in route handler files to provide OpenAPI metadata for each route. The `openAPI` property accepts a standard OpenAPI [Operation Object](https://spec.openapis.org/oas/v3.1.0#operation-object).
+
+```ts [routes/api/hello.ts]
+import { defineRouteMeta, defineHandler } from "nitro";
+
+defineRouteMeta({
+  openAPI: {
+    tags: ["greeting"],
+    description: "Returns a greeting message",
+    responses: {
+      200: { description: "Successful greeting" },
+    },
+  },
+});
+
+export default defineHandler(() => {
+  return { message: "Hello, world!" };
+});
+```
+
+<note>
+
+`defineRouteMeta` is a build-time macro. The metadata is statically extracted during the build and does not add any runtime overhead to your handlers.
+</note>
+
+### Parameters
+
+Route parameters (`:id`, `[id]`) are automatically converted to OpenAPI path parameters. You can define additional query or header parameters in the `parameters` array:
+
+```ts [routes/api/users/[id].get.ts]
+import { defineRouteMeta, defineHandler } from "nitro";
+
+defineRouteMeta({
+  openAPI: {
+    tags: ["users"],
+    description: "Get a user by their ID",
+    parameters: [
+      {
+        in: "query",
+        name: "include",
+        description: "Comma-separated list of related resources to include",
+        schema: { type: "string" },
+      },
+    ],
+    responses: {
+      200: { description: "User found" },
+      404: { description: "User not found" },
+    },
+  },
+});
+
+export default defineHandler((event) => {
+  const { id } = event.context.params;
+  return { id, name: "Alice" };
+});
+```
+
+In this example, the `id` path parameter is automatically inferred from the route pattern. Only the additional `include` query parameter needs to be declared.
+
+### Response Schemas
+
+Define response content types and schemas using the standard OpenAPI `responses` object:
+
+```ts [routes/api/status.ts]
+import { defineRouteMeta, defineHandler } from "nitro";
+
+defineRouteMeta({
+  openAPI: {
+    description: "Returns the current server status",
+    responses: {
+      200: {
+        description: "Server status",
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                status: { type: "string", enum: ["healthy", "degraded"] },
+                uptime: { type: "number" },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+});
+
+export default defineHandler(() => {
+  return { status: "healthy", uptime: process.uptime() };
+});
+```
+
+### Global Components
+
+Use the `$global` property to define reusable schemas that are hoisted to the top-level `components` section of the OpenAPI specification. This lets you reference shared schemas with `$ref` across multiple routes.
+
+```ts [routes/api/users.get.ts]
+import { defineRouteMeta, defineHandler } from "nitro";
+
+defineRouteMeta({
+  openAPI: {
+    tags: ["users"],
+    description: "List all users",
+    responses: {
+      200: {
+        description: "List of users",
+        content: {
+          "application/json": {
+            schema: {
+              type: "array",
+              items: { $ref: "#/components/schemas/User" },
+            },
+          },
+        },
+      },
+    },
+    $global: {
+      components: {
+        schemas: {
+          User: {
+            type: "object",
+            properties: {
+              id: { type: "string" },
+              name: { type: "string" },
+              email: { type: "string", format: "email" },
+            },
+          },
+        },
+      },
+    },
+  },
+});
+
+export default defineHandler(() => {
+  return [{ id: "1", name: "Alice", email: "alice@example.com" }];
+});
+```
+
+Once defined, the `User` schema can be referenced from any other route with `{ $ref: "#/components/schemas/User" }` without re-declaring it.
+
+### Automatic Tagging
+
+Routes are automatically tagged based on their path prefix:
+
+| Route prefix | Tag |
+| --- | --- |
+| `/api/` | API Routes |
+| `/_` | Internal |
+| Other | App Routes |
+
+You can override this by specifying `tags` in the `openAPI` metadata.
+
+## Configuration
+
+Configure OpenAPI behavior with the top-level `openAPI` option:
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  experimental: {
+    openAPI: true,
+  },
+  openAPI: {
+    meta: {
+      title: "My API",
+      description: "My awesome API",
+      version: "2.0.0",
+    },
+  },
+});
+```
+
+### `meta`
+
+Set the API metadata that appears in the specification's `info` object:
+
+| Property | Default | Description |
+| --- | --- | --- |
+| `title` | `"Nitro Server Routes"` | API title |
+| `description` | — | API description |
+| `version` | `"1.0.0"` | API version |
+
+### `route`
+
+- Default: `"/_openapi.json"`
+Override the path where the OpenAPI JSON specification is served:
+
+```ts [nitro.config.ts]
+export default defineConfig({
+  openAPI: {
+    route: "/_docs/openapi.json",
+  },
+});
+```
+
+### `ui`
+
+Configure or disable the built-in API documentation UIs:
+
+```ts [nitro.config.ts]
+export default defineConfig({
+  openAPI: {
+    ui: {
+      scalar: {
+        route: "/_docs/scalar",
+        theme: "purple",
+      },
+      swagger: {
+        route: "/_docs/swagger",
+      },
+    },
+  },
+});
+```
+
+Set either UI to `false` to disable it:
+
+```ts [nitro.config.ts]
+export default defineConfig({
+  openAPI: {
+    ui: {
+      swagger: false,
+    },
+  },
+});
+```
+
+<read-more></read-more>
+
+## Production
+
+By default, OpenAPI endpoints are only available during development. To enable them in production, set the `production` option:
+
+```ts [nitro.config.ts]
+export default defineConfig({
+  openAPI: {
+    production: "runtime",
+  },
+});
+```
+
+| Value | Behavior |
+| --- | --- |
+| `false` | Disabled in production (default) |
+| `"runtime"` | Specification is generated at runtime on each request |
+| `"prerender"` | Specification is generated at build time and served as a static file |
+
+Use `"prerender"` when the specification does not change between deployments for the best performance. Use `"runtime"` if you need dynamic server information or middleware access.
+
+<warning>
+
+If you enable OpenAPI in production, make sure to protect the endpoints with appropriate authentication or access control.
+</warning>

package/dist/docs/0.docs/12.plugins.md

@@ -0,0 +1,164 @@
+# Plugins
+
+> Use plugins to extend Nitro's runtime behavior.
+
+Nitro plugins are **executed once** during server startup in order to allow extending Nitro's runtime behavior.
+They receive `nitroApp` context, which can be used to hook into lifecycle events.
+
+Plugins are auto-registered from the `plugins/` directory and run synchronously by file name order on the first Nitro initialization. Plugin functions themselves must be synchronous (return `void`), but the hooks they register can be async.
+
+**Example:**
+
+```ts [plugins/test.ts]
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitroApp) => {
+  console.log('Nitro plugin', nitroApp)
+})
+```
+
+If you have plugins in another directory, you can use the `plugins` option:
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  plugins: ['my-plugins/hello.ts']
+})
+```
+
+## The `nitroApp` context
+
+The plugin function receives a `nitroApp` object with the following properties:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `hooks` | [`HookableCore`](https://github.com/unjs/hookable) | Hook system for registering lifecycle callbacks. |
+| `h3` | `H3Core` | The underlying [H3](https://github.com/h3js/h3) application instance. |
+| `fetch` | `(req: Request) => Response \| Promise<Response>` | The app's internal fetch handler. |
+| `captureError` | `(error: Error, context) => void` | Programmatically capture errors into the error hook pipeline. |
+
+## Nitro runtime hooks
+
+You can use Nitro [hooks](https://github.com/unjs/hookable) to extend the default runtime behaviour of Nitro by registering custom functions to the lifecycle events within plugins.
+
+**Example:**
+
+```ts
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitroApp) => {
+  nitroApp.hooks.hook("close", async () => {
+    // Will run when nitro is being closed
+  });
+})
+```
+
+### Available hooks
+
+| Hook | Signature | Description |
+| --- | --- | --- |
+| `request` | `(event: HTTPEvent) => void \| Promise<void>` | Called at the start of each request. |
+| `response` | `(res: Response, event: HTTPEvent) => void \| Promise<void>` | Called after the response is created. |
+| `error` | `(error: Error, context: { event?: HTTPEvent, tags?: string[] }) => void` | Called when an error is captured. |
+| `close` | `() => void` | Called when the Nitro server is shutting down. |
+
+> [!NOTE]
+> The `NitroRuntimeHooks` interface is augmentable. Deployment presets (such as Cloudflare) can extend it with platform-specific hooks like `cloudflare:scheduled` and `cloudflare:email`.
+
+### Unregistering hooks
+
+The `hook()` method returns an unregister function that can be called to remove the hook:
+
+```ts
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitroApp) => {
+  const unregister = nitroApp.hooks.hook("request", (event) => {
+    // ...
+  });
+
+  // Later, remove the hook
+  unregister();
+});
+```
+
+## Examples
+
+### Capturing errors
+
+You can use plugins to capture all application errors.
+
+```ts
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitroApp) => {
+  nitroApp.hooks.hook("error", async (error, { event }) => {
+    console.error(`${event?.path} Application error:`, error)
+  });
+})
+```
+
+The `context` object includes an optional `tags` array that identifies the error source (e.g., `"request"`, `"response"`, `"cache"`, `"plugin"`, `"unhandledRejection"`, `"uncaughtException"`).
+
+### Programmatic error capture
+
+You can use `captureError` to manually feed errors into the error hook pipeline:
+
+```ts
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitroApp) => {
+  nitroApp.captureError(new Error("something went wrong"), {
+    tags: ["startup"],
+  });
+});
+```
+
+### Graceful shutdown
+
+Server will gracefully shutdown and wait for any background pending tasks initiated by `event.waitUntil`.
+
+```ts
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitroApp) => {
+  nitroApp.hooks.hook("close", async () => {
+    // Clean up resources, close connections, etc.
+  });
+});
+```
+
+### Request and response lifecycle
+
+You can use plugins to register hooks that run on the request lifecycle:
+
+```ts
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitroApp) => {
+  nitroApp.hooks.hook("request", (event) => {
+    console.log("on request", event.path);
+  });
+
+  nitroApp.hooks.hook("response", (res, event) => {
+    // Modify or inspect the response
+    console.log("on response", res.status);
+  });
+});
+```
+
+### Modifying response headers
+
+```ts
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitroApp) => {
+  nitroApp.hooks.hook("response", (res, event) => {
+    const { pathname } = new URL(event.req.url);
+    if (pathname.endsWith(".css") || pathname.endsWith(".js")) {
+      res.headers.append("Vary", "Origin");
+    }
+  });
+});
+```