nitro 3.0.1-alpha.2 → 3.0.260415-beta

package/dist/docs/3.examples/0.index/index.md

@@ -0,0 +1,3 @@
+# Examples
+
+> Explore Nitro examples to learn how to build full-stack applications

package/dist/docs/3.examples/1.api-routes.md

@@ -0,0 +1,145 @@
+# API Routes
+
+> File-based API routing with HTTP method support and dynamic parameters.
+
+<code-tree>
+
+```html [index.html]
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>API Routes</title>
+  </head>
+  <body>
+    <h2>API Routes:</h2>
+    <ul>
+      <li><a href="/api/hello">/api/hello</a></li>
+      <li><a href="/api/hello/world">/api/hello/world</a></li>
+      <li><a href="/api/test">/api/test</a></li>
+    </ul>
+  </body>
+</html>
+```
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: "./",
+});
+```
+
+```json [package.json]
+{
+  "type": "module",
+  "scripts": {
+    "dev": "nitro dev",
+    "build": "nitro build"
+  },
+  "devDependencies": {
+    "nitro": "latest"
+  }
+}
+```
+
+```json [tsconfig.json]
+{
+  "extends": "nitro/tsconfig"
+}
+```
+
+```ts [vite.config.ts]
+import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
+
+export default defineConfig({ plugins: [nitro()] });
+```
+
+```ts [api/hello.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler(() => "Nitro is amazing!");
+```
+
+```ts [api/test.get.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler(() => "Test get handler");
+```
+
+```ts [api/test.post.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler(async (event) => {
+  const body = await event.req.json();
+  return {
+    message: "Test post handler",
+    body,
+  };
+});
+```
+
+```ts [api/hello/[name].ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler((event) => `Hello (param: ${event.context.params!.name})!`);
+```
+</code-tree>
+
+Nitro supports file-based routing in the `api/` or `routes/` directory. Each file becomes an API endpoint based on its path.
+
+## Basic Route
+
+Create a file in the `api/` directory to define a route. The file path becomes the URL path:
+
+```ts [api/hello.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler(() => "Nitro is amazing!");
+```
+
+This creates a `GET /api/hello` endpoint.
+
+## Dynamic Routes
+
+Use square brackets `[param]` for dynamic URL segments. Access params via `event.context.params`:
+
+```ts [api/hello/[name].ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler((event) => `Hello (param: ${event.context.params!.name})!`);
+```
+
+This creates a `GET /api/hello/:name` endpoint (e.g., `/api/hello/world`).
+
+## HTTP Methods
+
+Suffix your file with the HTTP method (`.get.ts`, `.post.ts`, `.put.ts`, `.delete.ts`, etc.):
+
+### GET Handler
+
+```ts [api/test.get.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler(() => "Test get handler");
+```
+
+### POST Handler
+
+```ts [api/test.post.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler(async (event) => {
+  const body = await event.req.json();
+  return {
+    message: "Test post handler",
+    body,
+  };
+});
+```
+
+## Learn More
+
+- [Routing](/docs/routing)

package/dist/docs/3.examples/10.hono.md

@@ -0,0 +1,74 @@
+# Hono
+
+> Integrate Hono with Nitro using the server entry.
+
+<code-tree>
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({});
+```
+
+```json [package.json]
+{
+  "type": "module",
+  "scripts": {
+    "build": "nitro build",
+    "dev": "nitro dev"
+  },
+  "devDependencies": {
+    "hono": "^4.12.9",
+    "nitro": "latest"
+  }
+}
+```
+
+```ts [server.ts]
+import { Hono } from "hono";
+
+const app = new Hono();
+
+app.get("/", (c) => {
+  return c.text("Hello, Hono with Nitro!");
+});
+
+export default app;
+```
+
+```json [tsconfig.json]
+{
+  "extends": "nitro/tsconfig"
+}
+```
+
+```ts [vite.config.ts]
+import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
+
+export default defineConfig({ plugins: [nitro()] });
+```
+</code-tree>
+
+## Server Entry
+
+```ts [server.ts]
+import { Hono } from "hono";
+
+const app = new Hono();
+
+app.get("/", (c) => {
+  return c.text("Hello, Hono with Nitro!");
+});
+
+export default app;
+```
+
+Nitro auto-detects `server.ts` in your project root and uses it as the server entry. The Hono app handles all incoming requests, giving you full control over routing and middleware.
+
+Hono is cross-runtime compatible, so this server entry works across all Nitro deployment targets including Node.js, Deno, Bun, and Cloudflare Workers.
+
+## Learn More
+
+- [Server Entry](/docs/server-entry)
+- [Hono Documentation](https://hono.dev/)

package/dist/docs/3.examples/11.import-alias.md

@@ -0,0 +1,97 @@
+# Import Alias
+
+> Custom import aliases for cleaner module paths.
+
+<code-tree>
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: true,
+});
+```
+
+```json [package.json]
+{
+  "type": "module",
+  "imports": {
+    "#server/*": "./server/*"
+  },
+  "scripts": {
+    "build": "nitro build",
+    "dev": "nitro dev",
+    "preview": "node .output/server/index.mjs"
+  },
+  "devDependencies": {
+    "nitro": "latest"
+  }
+}
+```
+
+```json [tsconfig.json]
+{
+  "extends": "nitro/tsconfig",
+  "compilerOptions": {
+    "paths": {
+      "~server/*": ["./server/*"]
+    }
+  }
+}
+```
+
+```ts [vite.config.ts]
+import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
+
+export default defineConfig({ plugins: [nitro()], resolve: { tsconfigPaths: true } });
+```
+
+```ts [server/routes/index.ts]
+import { sum } from "~server/utils/math.ts";
+
+import { rand } from "#server/utils/math.ts";
+
+export default () => {
+  const [a, b] = [rand(1, 10), rand(1, 10)];
+  const result = sum(a, b);
+  return `The sum of ${a} + ${b} = ${result}`;
+};
+```
+
+```ts [server/utils/math.ts]
+export function rand(min: number, max: number): number {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+export function sum(a: number, b: number): number {
+  return a + b;
+}
+```
+</code-tree>
+
+Import aliases like `~` and `#` let you reference modules with shorter paths instead of relative imports.
+
+## Importing Using Aliases
+
+```ts [server/routes/index.ts]
+import { sum } from "~server/utils/math.ts";
+
+import { rand } from "#server/utils/math.ts";
+
+export default () => {
+  const [a, b] = [rand(1, 10), rand(1, 10)];
+  const result = sum(a, b);
+  return `The sum of ${a} + ${b} = ${result}`;
+};
+```
+
+The route imports the `sum` function using `~server/` and `rand` using `#server/`. Both resolve to the same `server/utils/math.ts` file. The handler generates two random numbers and returns their sum.
+
+## Configuration
+
+Aliases can be configured in `package.json` imports field or `nitro.config.ts`.
+
+## Learn More
+
+- [Configuration](/docs/configuration)

package/dist/docs/3.examples/12.middleware.md

@@ -0,0 +1,91 @@
+# Middleware
+
+> Request middleware for authentication, logging, and request modification.
+
+<code-tree>
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: true,
+});
+```
+
+```json [package.json]
+{
+  "type": "module",
+  "scripts": {
+    "dev": "nitro dev",
+    "build": "nitro build"
+  },
+  "devDependencies": {
+    "nitro": "latest"
+  }
+}
+```
+
+```ts [server.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler((event) => ({
+  auth: event.context.auth,
+}));
+```
+
+```json [tsconfig.json]
+{
+  "extends": "nitro/tsconfig"
+}
+```
+
+```ts [vite.config.ts]
+import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
+
+export default defineConfig({ plugins: [nitro()] });
+```
+
+```ts [server/middleware/auth.ts]
+import { defineMiddleware } from "nitro";
+
+export default defineMiddleware((event) => {
+  event.context.auth = { name: "User " + Math.round(Math.random() * 100) };
+});
+```
+</code-tree>
+
+Middleware functions run before route handlers on every request. They can modify the request, add context, or return early responses.
+
+## Defining Middleware
+
+Create files in `server/middleware/`. They run in alphabetical order:
+
+```ts [server/middleware/auth.ts]
+import { defineMiddleware } from "nitro";
+
+export default defineMiddleware((event) => {
+  event.context.auth = { name: "User " + Math.round(Math.random() * 100) };
+});
+```
+
+Middleware can:
+
+- Add data to `event.context` for use in handlers
+- Return a response early to short-circuit the request
+- Modify request headers or other properties
+
+## Accessing Context in Handlers
+Data added to `event.context` in middleware is available in all subsequent handlers:
+
+```ts [server.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler((event) => ({
+  auth: event.context.auth,
+}));
+```
+
+## Learn More
+
+- [Routing](/docs/routing)

package/dist/docs/3.examples/13.mono-jsx.md

@@ -0,0 +1,68 @@
+# Mono JSX
+
+> Server-side JSX rendering in Nitro with mono-jsx.
+
+<code-tree>
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({});
+```
+
+```json [package.json]
+{
+  "type": "module",
+  "scripts": {
+    "dev": "nitro dev",
+    "build": "nitro build"
+  },
+  "devDependencies": {
+    "mono-jsx": "latest",
+    "nitro": "latest"
+  }
+}
+```
+
+```tsx [server.tsx]
+export default () => (
+  <html>
+    <h1>Nitro + mono-jsx works!</h1>
+  </html>
+);
+```
+
+```json [tsconfig.json]
+{
+  "extends": "nitro/tsconfig",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "mono-jsx"
+  }
+}
+```
+
+```ts [vite.config.ts]
+import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
+
+export default defineConfig({ plugins: [nitro()] });
+```
+</code-tree>
+
+## Server Entry
+
+```tsx [server.tsx]
+export default () => (
+  <html>
+    <h1>Nitro + mono-jsx works!</h1>
+  </html>
+);
+```
+
+Nitro auto-detects `server.tsx` and uses mono-jsx to transform JSX into HTML. Export a function that returns JSX, and Nitro sends the rendered HTML as the response.
+
+## Learn More
+
+- [Renderer](/docs/renderer)
+- [mono-jsx](https://github.com/aspect-dev/mono-jsx)

package/dist/docs/3.examples/14.nano-jsx.md

@@ -0,0 +1,70 @@
+# Nano JSX
+
+> Server-side JSX rendering in Nitro with nano-jsx.
+
+<code-tree>
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({});
+```
+
+```json [package.json]
+{
+  "type": "module",
+  "scripts": {
+    "dev": "nitro dev",
+    "build": "nitro build"
+  },
+  "devDependencies": {
+    "nano-jsx": "^0.2.1",
+    "nitro": "latest"
+  }
+}
+```
+
+```tsx [server.tsx]
+import { defineHandler, html } from "nitro";
+import { renderSSR } from "nano-jsx";
+
+export default defineHandler(() => {
+  return html(renderSSR(() => <h1>Nitro + nano-jsx works!</h1>));
+});
+```
+
+```json [tsconfig.json]
+{
+  "extends": "nitro/tsconfig",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "nano-jsx/esm"
+  }
+}
+```
+
+```ts [vite.config.ts]
+import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
+
+export default defineConfig({ plugins: [nitro()] });
+```
+</code-tree>
+
+## Server Entry
+
+```tsx [server.tsx]
+import { defineHandler, html } from "nitro";
+import { renderSSR } from "nano-jsx";
+
+export default defineHandler(() => {
+  return html(renderSSR(() => <h1>Nitro + nano-jsx works!</h1>));
+});
+```
+
+Nitro auto-detects `server.tsx` and uses it as the server entry. Use `renderSSR` from nano-jsx to convert JSX into an HTML string. The `html` helper from H3 sets the correct content type header.
+
+## Learn More
+
+- [Renderer](/docs/renderer)
+- [nano-jsx](https://nanojsx.io/)

package/dist/docs/3.examples/15.plugins.md

@@ -0,0 +1,91 @@
+# Plugins
+
+> Extend Nitro with custom plugins for hooks and lifecycle events.
+
+<code-tree>
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: true,
+});
+```
+
+```json [package.json]
+{
+  "type": "module",
+  "scripts": {
+    "dev": "nitro dev",
+    "build": "nitro build"
+  },
+  "devDependencies": {
+    "nitro": "latest"
+  }
+}
+```
+
+```ts [server.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler(() => "<h1>Hello Nitro!</h1>");
+```
+
+```json [tsconfig.json]
+{
+  "extends": "nitro/tsconfig"
+}
+```
+
+```ts [vite.config.ts]
+import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
+
+export default defineConfig({ plugins: [nitro()] });
+```
+
+```ts [server/plugins/test.ts]
+import { definePlugin } from "nitro";
+import { useNitroHooks } from "nitro/app";
+
+export default definePlugin((nitroApp) => {
+  const hooks = useNitroHooks();
+  hooks.hook("response", (event) => {
+    event.headers.set("content-type", "html; charset=utf-8");
+  });
+});
+```
+</code-tree>
+
+Plugins let you hook into Nitro's runtime lifecycle. This example shows a plugin that modifies the `Content-Type` header on every response. Create files in `server/plugins/` and they're automatically loaded at startup.
+
+## Defining a Plugin
+
+```ts [server/plugins/test.ts]
+import { definePlugin } from "nitro";
+import { useNitroHooks } from "nitro/app";
+
+export default definePlugin((nitroApp) => {
+  const hooks = useNitroHooks();
+  hooks.hook("response", (event) => {
+    event.headers.set("content-type", "html; charset=utf-8");
+  });
+});
+```
+
+The plugin uses `useNitroHooks()` to access the hooks system, then registers a `response` hook that runs after every request. Here it sets the content type to HTML, but you could log requests, add security headers, or modify responses in any way.
+
+## Main Handler
+
+```ts [server.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler(() => "<h1>Hello Nitro!</h1>");
+```
+
+The handler returns HTML without setting a content type. The plugin automatically adds the correct `Content-Type: html; charset=utf-8` header to the response.
+
+## Learn More
+
+- [Plugins](/docs/plugins)
+- [Lifecycle](/docs/lifecycle)