@depup/nitro 3.0.260311-beta-depup.0

package/skills/nitro/docs/docs/server-entry.md

@@ -0,0 +1,239 @@
+# Nitro Server Entry
+
+> Use a server entry to create a global middleware that runs for all routes before they are matched.
+
+The server entry is a special handler in Nitro that acts as a global middleware, running for every incoming request before routes are matched. It's commonly used for cross-cutting concerns like authentication, logging, request preprocessing, or creating custom routing logic.
+
+## Auto-detected `server.ts`
+
+By default, Nitro automatically looks for a `server.ts` (or `.js`, `.mjs`, `.mts`, `.tsx`, `.jsx`) file in your project root directory.
+
+If found, Nitro will use it as the server entry and run it for all incoming requests.
+
+<code-group>
+
+```ts [server.ts]
+export default {
+  async fetch(req: Request) {
+    const url = new URL(req.url);
+
+    // Handle specific routes
+    if (url.pathname === "/health") {
+      return new Response("OK", {
+        status: 200,
+        headers: { "content-type": "text/plain" }
+      });
+    }
+
+    // Add custom headers to all requests
+    // Return nothing to continue to the next handler
+  }
+}
+```
+
+```ts [routes/api/hello.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler((event) => {
+  return { hello: "API" };
+});
+```
+</code-group>
+
+<tip>
+
+When `server.ts` is detected, Nitro will log in the terminal: `Detected \`server.ts` as server entry.`
+</tip>
+
+With this setup:
+
+- `/health` → Handled by server entry (returns a response)
+- `/api/hello` → Handled by the API route handler directly
+- `/about`, etc. → Server entry runs first, then continues to the renderer if no response is returned
+
+## Framework compatibility
+The server entry is a great way to integrate with other frameworks. Any framework that exposes a standard Web `fetch(request: Request): Response` interface can be used as a server entry.
+
+### Web-compatible frameworks
+
+Frameworks that implement the Web `fetch` API work directly with `server.ts`:
+
+<tabs>
+
+<tabs-item>
+
+```ts [server.ts]
+import { H3 } from "h3";
+
+const app = new H3()
+
+app.get("/", () => "⚡️ Hello from H3!");
+
+export default app;
+```
+</tabs-item>
+
+<tabs-item>
+
+```ts [server.ts]
+import { Hono } from "hono";
+
+const app = new Hono();
+
+app.get("/", (c) => c.text("🔥 Hello from Hono!"));
+
+export default app;
+```
+</tabs-item>
+
+<tabs-item>
+
+```ts [server.ts]
+import { Elysia } from "elysia";
+
+const app = new Elysia();
+
+app.get("/", () => "🦊 Hello from Elysia!");
+
+export default app.compile();
+```
+</tabs-item>
+</tabs>
+
+### Node.js frameworks
+
+For Node.js frameworks that use `(req, res)` style handlers (like [Express](https://expressjs.com/) or [Fastify](https://fastify.dev/)), name your server entry file `server.node.ts` instead of `server.ts`. Nitro will automatically detect the `.node.` suffix and convert the Node.js handler to a web-compatible fetch handler using [`srvx`](https://srvx.h3.dev/).
+
+<tabs>
+
+<tabs-item>
+
+```ts [server.node.ts]
+import Express from "express";
+
+const app = Express();
+
+app.use("/", (_req, res) => {
+  res.send("Hello from Express with Nitro!");
+});
+
+export default app;
+```
+</tabs-item>
+
+<tabs-item>
+
+```ts [server.node.ts]
+import Fastify from "fastify";
+
+const app = Fastify();
+
+app.get("/", () => "Hello, Fastify with Nitro!");
+
+await app.ready();
+
+export default app.routing;
+```
+</tabs-item>
+</tabs>
+
+## Configuration
+
+### Custom server entry file
+
+You can specify a custom server entry file using the `serverEntry` option in your Nitro configuration:
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  serverEntry: "./nitro.server.ts"
+})
+```
+
+You can also provide an object with `handler` and `format` options:
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  serverEntry: {
+    handler: "./server.ts",
+    format: "node" // "web" (default) or "node"
+  }
+})
+```
+
+### Handler format
+
+The `format` option controls how Nitro treats the default export of your server entry:
+
+- **`"web"`** (default) — Expects a Web-compatible handler with a `fetch(request: Request): Response` method.
+- **`"node"`** — Expects a Node.js-style `(req, res)` handler. Nitro automatically converts it to a web-compatible handler.
+When auto-detecting, the format is determined by the filename: `server.node.ts` uses `"node"` format, while `server.ts` uses `"web"` format.
+
+### Disabling server entry
+
+Set `serverEntry` to `false` to disable auto-detection and prevent Nitro from using any server entry:
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  serverEntry: false
+})
+```
+
+## Using event handler
+
+You can also export an event handler using `defineHandler` for better type inference and access to the h3 event object:
+
+```ts [server.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler((event) => {
+  // Add custom context
+  event.context.requestId = crypto.randomUUID();
+  event.context.timestamp = Date.now();
+
+  // Log the request
+  console.log(`[${event.context.requestId}] ${event.method} ${event.path}`);
+
+  // Continue to the next handler (don't return anything)
+});
+```
+
+<important>
+
+If your server entry returns `undefined` or doesn't return anything, the request will continue to be processed by routes and the renderer. If it returns a response, the request lifecycle stops there.
+</important>
+
+## Request lifecycle
+
+The server entry is registered as a catch-all (`/**`) route handler. When a specific route (like `/api/hello`) matches a request, that route handler takes priority. For requests that don't match any specific route, the server entry runs before the renderer:
+
+```md
+1. Server hook: `request`
+2. Route rules (headers, redirects, etc.)
+3. Global middleware (middleware/)
+4. Route matching:
+   a. Specific routes (routes/) ← if matched, handles the request
+   b. Server entry ← runs for unmatched routes
+   c. Renderer (renderer.ts or index.html)
+```
+
+When both a server entry and a renderer exist, they are chained: the server entry runs first, and if it doesn't return a response, the renderer handles the request.
+
+## Development mode
+
+During development, Nitro watches for changes to your server entry file. When the file is created, modified, or deleted, the dev server automatically reloads to pick up the changes.
+
+## Best practices
+
+- Use server entry for cross-cutting concerns that affect **all routes**
+- Return `undefined` to continue processing, return a response to terminate
+- Keep server entry logic lightweight for better performance
+- Use global middleware for modular concerns instead of one large server entry
+- Consider using [Nitro plugins](/docs/plugins) for initialization logic
+- Avoid heavy computation in server entry (it runs for every request)
+- Don't use server entry for route-specific logic (use route handlers instead as they are more performant)

package/skills/nitro/docs/docs/storage.md

@@ -0,0 +1,261 @@
+# KV Storage
+
+> Nitro provides a built-in storage layer that can abstract filesystem or database or any other data source.
+
+Nitro has built-in integration with [unstorage](https://unstorage.unjs.io) to provide a runtime agnostic persistent layer.
+
+## Usage
+
+To use the storage layer, you can use the `useStorage()` utility to access the storage instance.
+
+```ts
+import { useStorage } from "nitro/storage";
+
+// Default storage (in-memory)
+await useStorage().setItem("test:foo", { hello: "world" });
+const value = await useStorage().getItem("test:foo");
+
+// You can specify a base prefix with useStorage(base)
+const testStorage = useStorage("test");
+await testStorage.setItem("foo", { hello: "world" });
+await testStorage.getItem("foo"); // { hello: "world" }
+
+// You can use generics to type the return value
+await useStorage<{ hello: string }>("test").getItem("foo");
+await useStorage("test").getItem<{ hello: string }>("foo");
+```
+
+<read-more></read-more>
+
+### Available methods
+
+The storage instance returned by `useStorage()` provides the following methods:
+
+| Method | Description |
+| --- | --- |
+| `getItem(key)` | Get the value of a key. Returns `null` if the key does not exist. |
+| `getItems(items)` | Get multiple items at once. Accepts an array of keys or `{ key, options }` objects. |
+| `getItemRaw(key)` | Get the raw value of a key without parsing. Useful for binary data. |
+| `setItem(key, value)` | Set the value of a key. |
+| `setItems(items)` | Set multiple items at once. Accepts an array of `{ key, value }` objects. |
+| `setItemRaw(key, value)` | Set the raw value of a key without serialization. |
+| `hasItem(key)` | Check if a key exists. Returns a boolean. |
+| `removeItem(key)` | Remove a key from storage. |
+| `getKeys(base?)` | Get all keys, optionally filtered by a base prefix. |
+| `clear(base?)` | Clear all keys, optionally filtered by a base prefix. |
+| `getMeta(key)` | Get metadata for a key (e.g., `mtime`, `atime`, `ttl`). |
+| `setMeta(key, meta)` | Set metadata for a key. |
+| `removeMeta(key)` | Remove metadata for a key. |
+| `mount(base, driver)` | Dynamically mount a storage driver at a base path. |
+| `unmount(base)` | Unmount a storage driver from a base path. |
+| `watch(callback)` | Watch for changes. Callback receives `(event, key)` where event is `"update"` or `"remove"`. |
+| `unwatch()` | Stop watching for changes. |
+
+Shorthand aliases are also available: `get`, `set`, `has`, `del`, `remove`, `keys`.
+
+```ts
+import { useStorage } from "nitro/storage";
+
+// Get all keys under a prefix
+const keys = await useStorage("test").getKeys();
+
+// Check if a key exists
+const exists = await useStorage().hasItem("test:foo");
+
+// Remove a key
+await useStorage().removeItem("test:foo");
+
+// Get raw binary data
+const raw = await useStorage().getItemRaw("assets/server:image.png");
+
+// Get metadata (type, etag, mtime, etc.)
+const meta = await useStorage("assets/server").getMeta("file.txt");
+```
+
+## Configuration
+
+You can mount one or multiple custom storage drivers using the `storage` option.
+
+The key is the mount point name, and the value is the driver name and configuration.
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  storage: {
+    redis: {
+      driver: "redis",
+      /* redis connector options */
+    }
+  }
+})
+```
+
+Then, you can use the redis storage using the `useStorage("redis")` function.
+
+<read-more>
+
+You can find the driver list on [unstorage documentation](https://unstorage.unjs.io/) with their configuration.
+</read-more>
+
+### Development storage
+
+You can use the `devStorage` option to override storage configuration during development and prerendering.
+
+This is useful when your production driver is not available in development (e.g., a managed Redis instance).
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  storage: {
+    db: {
+      driver: "redis",
+      host: "prod.example.com",
+    }
+  },
+  devStorage: {
+    db: {
+      driver: "fs",
+      base: "./.data/db"
+    }
+  }
+})
+```
+
+When running in development mode, `devStorage` mounts are merged on top of `storage` mounts, allowing you to use a local filesystem driver or an in-memory driver while developing.
+
+## Built-in mount points
+
+Nitro automatically mounts the following storage paths:
+
+### `/assets`
+
+Server assets are mounted at the `/assets` base path. This mount point provides read-only access to bundled server assets (see [Server assets](#server-assets)).
+
+```ts
+import { useStorage } from "nitro/storage";
+
+// Access server assets via the /assets mount
+const content = await useStorage("assets/server").getItem("my-file.txt");
+```
+
+### Default (in-memory)
+
+The root storage (without a base path) uses an in-memory driver by default. Data stored here is not persisted across restarts.
+
+```ts
+import { useStorage } from "nitro/storage";
+
+// In-memory by default, not persisted
+await useStorage().setItem("counter", 1);
+```
+
+To persist data, mount a driver with a persistent backend (e.g., `fs`, `redis`, etc.) using the `storage` configuration option.
+
+## Server assets
+
+Nitro allows you to bundle files from an `assets/` directory at the root of your project. These files are accessible at runtime via the `assets/server` storage mount.
+
+```
+my-project/
+  assets/
+    data.json
+    templates/
+      welcome.html
+  server/
+    routes/
+      index.ts
+```
+
+```ts [server/routes/index.ts]
+import { useStorage } from "nitro/storage";
+
+export default defineHandler(async () => {
+  const serverAssets = useStorage("assets/server");
+
+  const keys = await serverAssets.getKeys();
+  const data = await serverAssets.getItem("data.json");
+  const template = await serverAssets.getItem("templates/welcome.html");
+
+  return { keys, data, template };
+});
+```
+
+### Custom asset directories
+
+You can register additional asset directories using the `serverAssets` config option:
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  serverAssets: [
+    {
+      baseName: "templates",
+      dir: "./templates",
+    }
+  ]
+})
+```
+
+Custom asset directories are accessible under `assets/<baseName>`:
+
+```ts
+import { useStorage } from "nitro/storage";
+
+const templates = useStorage("assets/templates");
+const keys = await templates.getKeys();
+const html = await templates.getItem("email.html");
+```
+
+### Asset metadata
+
+Server assets include metadata such as content type, ETag, and modification time:
+
+```ts
+import { useStorage } from "nitro/storage";
+
+const serverAssets = useStorage("assets/server");
+
+const meta = await serverAssets.getMeta("image.png");
+// { type: "image/png", etag: "\"...\"", mtime: "2024-01-01T00:00:00.000Z" }
+
+// Useful for setting response headers
+const raw = await serverAssets.getItemRaw("image.png");
+```
+
+<note>
+
+In development, server assets are read directly from the filesystem. In production, they are bundled and inlined into the build output.
+</note>
+
+## Runtime configuration
+
+In scenarios where the mount point configuration is not known until runtime, Nitro can dynamically add mount points during startup using [plugins](/docs/plugins).
+
+```ts [plugins/storage.ts]
+import { useStorage } from "nitro/storage";
+import { definePlugin } from "nitro";
+import redisDriver from "unstorage/drivers/redis";
+
+export default definePlugin(() => {
+  const storage = useStorage()
+
+  // Dynamically pass in credentials from runtime configuration, or other sources
+  const driver = redisDriver({
+    base: "redis",
+    host: process.env.REDIS_HOST,
+    port: process.env.REDIS_PORT,
+    /* other redis connector options */
+  })
+
+  // Mount driver
+  storage.mount("redis", driver)
+})
+```
+
+<warning>
+
+This is a temporary workaround, with a better solution coming in the future! Keep a lookout on the GitHub issue [here](https://github.com/nitrojs/nitro/issues/1161#issuecomment-1511444675).
+</warning>