@depup/nitro 3.0.260311-beta-depup.0

package/skills/nitro/docs/docs/database.md

@@ -0,0 +1,185 @@
+> Nitro provides a built-in and lightweight SQL database layer.
+
+The default database connection is **preconfigured** with [SQLite](https://db0.unjs.io/connectors/sqlite) and works out of the box for development mode and any Node.js compatible production deployments. By default, data will be stored in `.data/db.sqlite`.
+
+<read-more></read-more>
+
+> [!IMPORTANT]
+> Database support is currently experimental.
+> Refer to the [db0 issues](https://github.com/unjs/db0/issues) for status and bug report.
+
+In order to enable database layer you need to enable experimental feature flag.
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  experimental: {
+    database: true
+  }
+})
+```
+
+> [!TIP]
+> You can change default connection or define more connections to any of the [supported databases](https://db0.unjs.io/connectors/sqlite).
+
+> [!TIP]
+> You can integrate database instance to any of the [supported ORMs](https://db0.unjs.io/integrations).
+
+## Usage
+
+```ts [server.ts]
+import { defineHandler } from "nitro";
+import { useDatabase } from "nitro/database";
+
+export default defineHandler(async () => {
+  const db = useDatabase();
+
+  // Create users table
+  await db.sql`DROP TABLE IF EXISTS users`;
+  await db.sql`CREATE TABLE IF NOT EXISTS users ("id" TEXT PRIMARY KEY, "firstName" TEXT, "lastName" TEXT, "email" TEXT)`;
+
+  // Add a new user
+  const userId = String(Math.round(Math.random() * 10_000));
+  await db.sql`INSERT INTO users VALUES (${userId}, 'John', 'Doe', '')`;
+
+  // Query for users
+  const { rows } = await db.sql`SELECT * FROM users WHERE id = ${userId}`;
+
+  return {
+    rows,
+  };
+});
+```
+
+### `useDatabase`
+
+Use `useDatabase` to get a database instance. It accepts an optional connection name (defaults to `"default"`).
+
+```ts
+import { useDatabase } from "nitro/database";
+
+// Use the default connection
+const db = useDatabase();
+
+// Use a named connection
+const usersDb = useDatabase("users");
+```
+
+> [!NOTE]
+> When `experimental.database` is enabled, `useDatabase` is auto-imported and available without an explicit import statement.
+
+Database instances are created lazily on first use and cached for subsequent calls with the same connection name. If a connection name is not configured, an error will be thrown.
+
+### `db.sql`
+
+Execute SQL queries using tagged template literals with automatic parameter binding:
+
+```ts
+const db = useDatabase();
+
+// Insert with parameterized values (safe from SQL injection)
+const id = "1001";
+await db.sql`INSERT INTO users VALUES (${id}, 'John', 'Doe', 'john@example.com')`;
+
+// Query with parameters
+const { rows } = await db.sql`SELECT * FROM users WHERE id = ${id}`;
+
+// The result includes rows, changes count, and last insert ID
+const result = await db.sql`INSERT INTO posts (title) VALUES (${"Hello"})`;
+// result.rows, result.changes, result.lastInsertRowid
+```
+
+### `db.exec`
+
+Execute a raw SQL string directly:
+
+```ts
+const db = useDatabase();
+
+await db.exec("CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)");
+```
+
+### `db.prepare`
+
+Prepare an SQL statement for repeated execution:
+
+```ts
+const db = useDatabase();
+
+const stmt = db.prepare("SELECT * FROM users WHERE id = ?");
+const result = await stmt.bind("1001").all();
+```
+
+## Configuration
+
+You can configure database connections using `database` config:
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  database: {
+    default: {
+      connector: "sqlite",
+      options: { name: "db" }
+    },
+    users: {
+      connector: "postgresql",
+      options: {
+        url: "postgresql://username:password@hostname:port/database_name"
+      },
+    },
+  },
+});
+```
+
+### Development Database
+
+Use the `devDatabase` config to override the database configuration **only for development mode**. This is useful for using a local SQLite database during development while targeting a different database in production.
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  database: {
+    default: {
+      connector: "postgresql",
+      options: {
+        url: "postgresql://username:password@hostname:port/database_name"
+      }
+    }
+  },
+  devDatabase: {
+    default: {
+      connector: "sqlite",
+      options: { name: "dev-db" }
+    }
+  }
+});
+```
+
+> [!TIP]
+> When `experimental.database` is enabled and no `database` or `devDatabase` config is provided, Nitro automatically configures a default SQLite connection. In development mode, data is stored relative to the project root directory. In Node.js production, it uses the default SQLite path.
+
+## Connectors
+
+Nitro supports all [db0 connectors](https://db0.unjs.io/connectors). The `connector` field in the database config accepts any of the following values:
+
+| Connector | Description |
+| --- | --- |
+| `sqlite` | Node.js built-in SQLite (alias for `node-sqlite`) |
+| `node-sqlite` | Node.js built-in SQLite |
+| `better-sqlite3` | [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) |
+| `sqlite3` | [sqlite3](https://github.com/TryGhost/node-sqlite3) |
+| `bun` / `bun-sqlite` | Bun built-in SQLite |
+| `libsql` / `libsql-node` | [libSQL](https://github.com/tursodatabase/libsql) (Node.js) |
+| `libsql-http` | libSQL over HTTP |
+| `libsql-web` | libSQL for web environments |
+| `postgresql` | [PostgreSQL](https://github.com/porsager/postgres) |
+| `mysql2` | [MySQL](https://github.com/sidorares/node-mysql2) |
+| `pglite` | [PGlite](https://github.com/electric-sql/pglite) (embedded PostgreSQL) |
+| `planetscale` | [PlanetScale](https://github.com/planetscale/database-js) serverless |
+| `cloudflare-d1` | [Cloudflare D1](https://developers.cloudflare.com/d1/) |
+| `cloudflare-hyperdrive-mysql` | Cloudflare Hyperdrive with MySQL |
+| `cloudflare-hyperdrive-postgresql` | Cloudflare Hyperdrive with PostgreSQL |

package/skills/nitro/docs/docs/index.md

@@ -0,0 +1,56 @@
+# Introduction
+
+> Nitro is a full-stack server framework, compatible with any runtime and any deployment target.
+
+Nitro gives you a production-ready server with filesystem routing, code-splitting, and built-in support for storage, caching, and databases — all runtime-agnostic and deployable anywhere.
+
+## What is Nitro?
+
+Create server and API routes inside the `routes/` directory. Each file maps directly to a URL path, and Nitro handles the rest — routing, code-splitting, and optimized builds.
+
+You can also take full control of the server entry by creating a `server.ts` file. Nitro’s high-level, runtime-agnostic approach lets you use any HTTP library, such as [Elysia](https://elysiajs.com/), [h3](https://h3.dev), or [Hono](https://hono.dev).
+
+### Performance
+
+Nitro compiles your routes at build time, removing the need for a runtime router. Only the code required to handle each incoming request is loaded and executed. This makes it ideal for serverless hosting, with near-0ms boot time regardless of project size.
+
+### Deploy Anywhere
+
+Build your server into an optimized `.output/` folder compatible with Node.js, Bun, Deno, and many hosting platforms without any configuration — Cloudflare Workers, Netlify, Vercel, and more. Take advantage of platform features like ESR, ISR, and SWR without changing a single line of code.
+
+### Server-Side Rendering
+
+Render HTML with your favorite templating engine, or use component libraries such as React, Vue, or Svelte directly on the server. Go full universal rendering with client-side hydration. Nitro provides the foundation and a progressive approach to reach your goals.
+
+### Storage
+
+Nitro includes a runtime-agnostic key-value storage layer out of the box. It uses in-memory storage by default, but you can connect more than 20 different drivers (FS, Redis, S3, etc.), attach them to different namespaces, and swap them without changing your code.
+
+### Caching
+
+Nitro supports caching for both server routes and server functions, backed directly by the server storage (via the `cache` namespace).
+
+### Database
+
+Nitro also includes a built-in SQL database. It defaults to SQLite, but you can connect to and query more than 10 databases (Postgres, MySQL, PGLite, etc.) using the same API.
+
+### Meta-Framework Foundation
+
+Nitro can be used as the foundation for building your own meta-framework. Popular frameworks such as Nuxt, SolidStart, and TanStack Start fully or partially leverage Nitro.
+
+## Vite Integration
+
+Nitro integrates seamlessly with [Vite](https://vite.dev) as a plugin. If you’re building a frontend application with Vite, adding Nitro gives you API routes, server-side rendering, and a full production server — all built together with `vite build`.
+
+```ts [vite.config.ts]
+import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
+
+export default defineConfig({
+  plugins: [nitro()],
+});
+```
+
+With Nitro, `vite build` produces an optimized `.output/` folder containing both your frontend and backend — ready to deploy anywhere.
+
+Ready to give it a try? Jump into the [quick start](/docs/quick-start).

package/skills/nitro/docs/docs/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 { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  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 { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  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/skills/nitro/docs/docs/migration.md

@@ -0,0 +1,215 @@
+# 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 { defineNitroConfig } from "nitro/config"
+```
+
+## 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 preset uses [srvx](https://srvx.unjs.io/) as the underlying server layer. The Cloudflare runtime context is now attached to the request's runtime object instead of the event context.
+
+**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/skills/nitro/docs/docs/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>