nitro 3.0.1-alpha.2 → 3.0.260415-beta

package/dist/docs/3.examples/16.renderer.md

@@ -0,0 +1,113 @@
+# Custom Renderer
+
+> Build a custom HTML renderer in Nitro with server-side data fetching.
+
+<code-tree>
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: "./",
+  renderer: { handler: "./renderer" },
+});
+```
+
+```json [package.json]
+{
+  "type": "module",
+  "scripts": {
+    "dev": "nitro dev",
+    "build": "nitro build"
+  },
+  "devDependencies": {
+    "nitro": "latest"
+  }
+}
+```
+
+```ts [renderer.ts]
+import { fetch } from "nitro";
+
+export default async function renderer({ url }: { req: Request; url: URL }) {
+  const apiRes = await fetch("/api/hello").then((res) => res.text());
+  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>
+      <p>API says: ${apiRes}</p>
+    </body>
+    </html>`,
+    { headers: { "content-type": "text/html; charset=utf-8" } }
+  );
+}
+```
+
+```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!");
+```
+</code-tree>
+
+Create a custom renderer that generates HTML responses with data from API routes. Use Nitro's internal `fetch` to call routes without network overhead.
+
+## Renderer
+
+```ts [renderer.ts]
+import { fetch } from "nitro";
+
+export default async function renderer({ url }: { req: Request; url: URL }) {
+  const apiRes = await fetch("/api/hello").then((res) => res.text());
+  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>
+      <p>API says: ${apiRes}</p>
+    </body>
+    </html>`,
+    { headers: { "content-type": "text/html; charset=utf-8" } }
+  );
+}
+```
+
+Nitro auto-detects `renderer.ts` in your project root and uses it for all non-API routes. The renderer function receives the request URL and returns a `Response`.
+
+Use `fetch` from `nitro` to call API routes without network overhead—these requests stay in-process.
+
+## API Route
+
+```ts [api/hello.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler(() => "Nitro is amazing!");
+```
+
+Define API routes in the `api/` directory. When the renderer calls `fetch("/api/hello")`, this handler runs and returns its response.
+
+## Learn More
+
+- [Renderer](/docs/renderer)

package/dist/docs/3.examples/17.runtime-config.md

@@ -0,0 +1,97 @@
+# Runtime Config
+
+> Environment-aware configuration with runtime access.
+
+<code-tree>
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: "./",
+  runtimeConfig: {
+    apiKey: "",
+  },
+});
+```
+
+```json [package.json]
+{
+  "type": "module",
+  "scripts": {
+    "dev": "nitro dev",
+    "build": "nitro build"
+  },
+  "devDependencies": {
+    "nitro": "latest"
+  }
+}
+```
+
+```ts [server.ts]
+import { defineHandler } from "nitro";
+import { useRuntimeConfig } from "nitro/runtime-config";
+
+export default defineHandler((event) => {
+  const runtimeConfig = useRuntimeConfig();
+  return { runtimeConfig };
+});
+```
+
+```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>
+
+Runtime config lets you define configuration values that can be overridden by environment variables at runtime.
+
+## Define Config Schema
+
+Declare your runtime config with default values in `nitro.config.ts`:
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: "./",
+  runtimeConfig: {
+    apiKey: "",
+  },
+});
+```
+
+## Access at Runtime
+
+Use `useRuntimeConfig` to access configuration values in your handlers:
+
+```ts [server.ts]
+import { defineHandler } from "nitro";
+import { useRuntimeConfig } from "nitro/runtime-config";
+
+export default defineHandler((event) => {
+  const runtimeConfig = useRuntimeConfig();
+  return { runtimeConfig };
+});
+```
+
+## Environment Variables
+
+Override config values via environment variables prefixed with `NITRO_`:
+
+```sh [.env]
+# NEVER COMMIT SENSITIVE DATA. THIS IS ONLY FOR DEMO PURPOSES.
+NITRO_API_KEY=secret-api-key
+```
+
+## Learn More
+
+- [Configuration](/docs/configuration)

package/dist/docs/3.examples/18.server-fetch.md

@@ -0,0 +1,87 @@
+# Server Fetch
+
+> Internal server-to-server requests without network overhead.
+
+<code-tree>
+
+```ts [nitro.config.ts]
+import { defineConfig, serverFetch } from "nitro";
+
+export default defineConfig({
+  serverDir: "./",
+  hooks: {
+    "dev:start": async () => {
+      const res = await serverFetch("/hello");
+      const text = await res.text();
+      console.log("Fetched /hello in nitro module:", res.status, text);
+    },
+  },
+});
+```
+
+```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 [routes/hello.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler(() => "Hello!");
+```
+
+```ts [routes/index.ts]
+import { defineHandler } from "nitro";
+import { fetch } from "nitro";
+
+export default defineHandler(() => fetch("/hello"));
+```
+</code-tree>
+
+When you need one route to call another, use Nitro's `fetch` function instead of the global fetch. It makes internal requests that stay in-process, avoiding network round-trips. The request never leaves the server.
+
+## Main Route
+
+```ts [routes/index.ts]
+import { defineHandler } from "nitro";
+import { fetch } from "nitro";
+
+export default defineHandler(() => fetch("/hello"));
+```
+
+The index route imports `fetch` from `nitro` (not the global fetch) and calls the `/hello` route. This request is handled internally without going through the network stack.
+
+## Internal API Route
+
+```ts [routes/hello.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler(() => "Hello!");
+```
+
+A simple route that returns "Hello!". When the index route calls `fetch("/hello")`, this handler runs and its response is returned directly.
+
+## Learn More
+
+- [Routing](/docs/routing)

package/dist/docs/3.examples/19.shiki.md

@@ -0,0 +1,198 @@
+# Shiki
+
+> Server-side syntax highlighting in Nitro with Shiki.
+
+<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>Hello World Snippet</title>
+    <link rel="stylesheet" href="styles.css" />
+  </head>
+  <body>
+    <div class="card" role="region" aria-label="Code snippet">
+      <div class="label">JavaScript</div>
+      <script server>
+        const hl = (code) =>
+          serverFetch("/api/highlight", {
+            method: "POST",
+            body: code,
+          });
+      </script>
+      <pre><code>{{{ hl(`console.log("💚 Simple is beautiful!");`) }}}</code></pre>
+    </div>
+  </body>
+</html>
+```
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: "./",
+});
+```
+
+```json [package.json]
+{
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build"
+  },
+  "devDependencies": {
+    "nitro": "latest",
+    "shiki": "latest"
+  }
+}
+```
+
+```css [styles.css]
+html,
+body {
+  height: 100%;
+  margin: 0;
+}
+body {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: #f6f8fa;
+  font-family:
+    system-ui,
+    -apple-system,
+    "Segoe UI",
+    Roboto,
+    "Helvetica Neue",
+    Arial,
+    "Noto Sans",
+    "Liberation Sans",
+    sans-serif;
+}
+.card {
+  text-align: left;
+  background: #0b1220;
+  color: #e6edf3;
+  padding: 1rem;
+  border-radius: 8px;
+  box-shadow: 0 8px 24px rgba(2, 6, 23, 0.2);
+  max-width: 90%;
+  width: 520px;
+}
+.label {
+  font-size: 12px;
+  color: #9aa7b2;
+  margin-bottom: 8px;
+}
+pre {
+  margin: 0;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, "Courier New", monospace;
+  font-size: 14px;
+  background: transparent;
+  white-space: pre;
+  overflow: auto;
+}
+```
+
+```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/highlight.ts]
+import { createHighlighterCore } from "shiki/core";
+import { createOnigurumaEngine } from "shiki/engine/oniguruma";
+
+const highlighter = await createHighlighterCore({
+  engine: createOnigurumaEngine(import("shiki/wasm")),
+  themes: [await import("shiki/themes/vitesse-dark.mjs")],
+  langs: [await import("shiki/langs/ts.mjs")],
+});
+
+export default async ({ req }: { req: Request }) => {
+  const code = await req.text();
+  const html = await highlighter.codeToHtml(code, {
+    lang: "ts",
+    theme: "vitesse-dark",
+  });
+  return new Response(html, {
+    headers: { "Content-Type": "text/html; charset=utf-8" },
+  });
+};
+```
+</code-tree>
+
+Use Shiki for syntax highlighting with TextMate grammars. This example highlights code on the server using Nitro's server scripts feature, which runs JavaScript inside HTML files before sending the response.
+
+## API Route
+
+```ts [api/highlight.ts]
+import { createHighlighterCore } from "shiki/core";
+import { createOnigurumaEngine } from "shiki/engine/oniguruma";
+
+const highlighter = await createHighlighterCore({
+  engine: createOnigurumaEngine(import("shiki/wasm")),
+  themes: [await import("shiki/themes/vitesse-dark.mjs")],
+  langs: [await import("shiki/langs/ts.mjs")],
+});
+
+export default async ({ req }: { req: Request }) => {
+  const code = await req.text();
+  const html = await highlighter.codeToHtml(code, {
+    lang: "ts",
+    theme: "vitesse-dark",
+  });
+  return new Response(html, {
+    headers: { "Content-Type": "text/html; charset=utf-8" },
+  });
+};
+```
+
+Create a Shiki highlighter with the Vitesse Dark theme and TypeScript language support. When the API receives a POST request, it reads the code from the request body and returns highlighted HTML.
+
+## Server-Side Rendering
+
+```html [index.html]
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>Hello World Snippet</title>
+    <link rel="stylesheet" href="styles.css" />
+  </head>
+  <body>
+    <div class="card" role="region" aria-label="Code snippet">
+      <div class="label">JavaScript</div>
+      <script server>
+        const hl = (code) =>
+          serverFetch("/api/highlight", {
+            method: "POST",
+            body: code,
+          });
+      </script>
+      <pre><code>{{{ hl(`console.log("💚 Simple is beautiful!");`) }}}</code></pre>
+    </div>
+  </body>
+</html>
+```
+
+The `<script server>` tag runs on the server before the HTML is sent. It defines a helper function that calls the highlight API using `serverFetch`. The triple-brace syntax `{{{ }}}` outputs the result without escaping, so the highlighted HTML renders correctly.
+
+## Learn More
+
+- [Shiki](https://shiki.style/)

package/dist/docs/3.examples/2.auto-imports.md

@@ -0,0 +1,92 @@
+# Auto Imports
+
+> Automatic imports for utilities and composables.
+
+<code-tree>
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: true,
+  imports: {},
+});
+```
+
+```json [package.json]
+{
+  "type": "module",
+  "scripts": {
+    "dev": "nitro dev",
+    "build": "nitro build"
+  },
+  "devDependencies": {
+    "nitro": "latest"
+  }
+}
+```
+
+```ts [server.ts]
+import { defineHandler } from "nitro";
+import { makeGreeting } from "./server/utils/hello.ts";
+
+export default defineHandler(() => `<h1>${makeGreeting("Nitro")}</h1>`);
+```
+
+```json [tsconfig.json]
+{
+  "include": [".nitro/types/nitro-imports.d.ts", "src"]
+}
+```
+
+```ts [vite.config.ts]
+import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
+
+export default defineConfig({ plugins: [nitro()] });
+```
+
+```ts [server/utils/hello.ts]
+export function makeGreeting(name: string) {
+  return `Hello, ${name}!`;
+}
+```
+</code-tree>
+
+Functions exported from `server/utils/` are automatically available without explicit imports when auto-imports are enabled. Define a utility once and use it anywhere in your server code.
+
+## Configuration
+
+Enable auto-imports by setting `imports` in your config:
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: true,
+  imports: {},
+});
+```
+
+## Using Auto Imports
+
+1. Create a utility file in `server/utils/`:
+
+```ts [server/utils/hello.ts]
+export function makeGreeting(name: string) {
+  return `Hello, ${name}!`;
+}
+```
+
+2. The function is available without importing it:
+
+```ts [server.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler(() => `<h1>${makeGreeting("Nitro")}</h1>`);
+```
+With this setup, any function exported from `server/utils/` becomes globally available. Nitro scans the directory and generates the necessary imports automatically.
+
+## Learn More
+
+- [Configuration](/docs/configuration)

package/dist/docs/3.examples/20.virtual-routes.md

@@ -0,0 +1,74 @@
+# Virtual Routes
+
+> Define routes programmatically using Nitro's virtual module system.
+
+<code-tree>
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  routes: {
+    "/": "#virtual-route",
+  },
+  virtual: {
+    "#virtual-route": () =>
+      /* js */ `export default () => new Response("Hello from virtual entry!")`,
+  },
+});
+```
+
+```json [package.json]
+{
+  "type": "module",
+  "scripts": {
+    "build": "nitro build",
+    "dev": "nitro dev",
+    "preview": "node .output/server/index.mjs"
+  },
+  "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()] });
+```
+</code-tree>
+
+Virtual routes let you define handlers as strings in your config instead of creating separate files. This is useful when generating routes dynamically, building plugins, or keeping simple routes inline.
+
+## Configuration
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  routes: {
+    "/": "#virtual-route",
+  },
+  virtual: {
+    "#virtual-route": () =>
+      /* js */ `export default () => new Response("Hello from virtual entry!")`,
+  },
+});
+```
+
+The `routes` option maps URL paths to virtual module identifiers (prefixed with `#`). The `virtual` option defines the module content as a string or function returning a string. At build time, Nitro resolves these virtual modules to actual handlers.
+
+There are no route files in this project. The entire handler is defined inline in the config, and Nitro generates the route at build time.
+
+## Learn More
+
+- [Routing](/docs/routing)
+- [Configuration](/docs/configuration)