@depup/nitro 3.0.260311-beta-depup.0

package/skills/nitro/docs/docs/tasks.md

@@ -0,0 +1,277 @@
+# Tasks
+
+> Nitro tasks allow on-off operations in runtime.
+
+## Opt-in to the experimental feature
+
+> [!IMPORTANT]
+> Tasks support is currently experimental.
+> See [nitrojs/nitro#1974](https://github.com/nitrojs/nitro/issues/1974) for the relevant discussion.
+
+In order to use the tasks API you need to enable experimental feature flag.
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  experimental: {
+    tasks: true
+  }
+})
+```
+
+## Define tasks
+
+Tasks can be defined in `tasks/[name].ts` files.
+
+Nested directories are supported. The task name will be joined with `:`. (Example: `tasks/db/migrate.ts` task name will be `db:migrate`)
+
+**Example:**
+
+```ts [tasks/db/migrate.ts]
+export default defineTask({
+  meta: {
+    name: "db:migrate",
+    description: "Run database migrations",
+  },
+  run({ payload, context }) {
+    console.log("Running DB migration task...");
+    return { result: "Success" };
+  },
+});
+```
+
+### Task interface
+
+The `defineTask` helper accepts an object with the following properties:
+
+- **`meta`** (optional): An object with optional `name` and `description` string fields used for display in the dev server and CLI.
+- **`run`** (required): A function that receives a [`TaskEvent`](#taskevent) and returns (or resolves to) an object with an optional `result` property.
+
+```ts
+interface Task<RT = unknown> {
+  meta?: { name?: string; description?: string };
+  run(event: TaskEvent): { result?: RT } | Promise<{ result?: RT }>;
+}
+```
+
+### `TaskEvent`
+The `run` function receives a `TaskEvent` object with the following properties:
+
+- **`name`**: The name of the task being executed.
+- **`payload`**: An object (`Record<string, unknown>`) containing any data passed to the task.
+- **`context`**: A `TaskContext` object (may include `waitUntil` depending on the runtime).
+
+```ts
+interface TaskEvent {
+  name: string;
+  payload: TaskPayload;
+  context: TaskContext;
+}
+```
+
+### Registering tasks via config
+In addition to file-based scanning, tasks can be registered directly in the Nitro config. This is useful for tasks provided by modules or pointing to custom handler paths.
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  experimental: {
+    tasks: true
+  },
+  tasks: {
+    "db:migrate": {
+      handler: "./tasks/custom-migrate.ts",
+      description: "Run database migrations"
+    }
+  }
+})
+```
+
+If a task is both scanned from the `tasks/` directory and defined in the config, the config-defined `handler` takes precedence.
+
+## Scheduled tasks
+
+You can define scheduled tasks using Nitro configuration to automatically run after each period of time.
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  scheduledTasks: {
+    // Run `cms:update` task every minute
+    '* * * * *': ['cms:update'],
+    // Run a single task (string shorthand)
+    '0 * * * *': 'db:cleanup'
+  }
+})
+```
+
+The `scheduledTasks` config maps cron expressions to either a single task name (string) or an array of task names. When multiple tasks are assigned to the same cron expression, they run in parallel.
+
+> [!TIP]
+> You can use [crontab.guru](https://crontab.guru/) to easily generate and understand cron tab patterns.
+
+When a scheduled task runs, it automatically receives a `payload` with `scheduledTime` set to the current timestamp (`Date.now()`).
+
+### Platform support
+
+- **`dev`**, **`node_server`**, **`node_cluster`**, **`node_middleware`**, **`bun`** and **`deno_server`** presets are supported with the [croner](https://croner.56k.guru/) engine.
+- **`cloudflare_module`** and **`cloudflare_pages`** presets have native integration with [Cron Triggers](https://developers.cloudflare.com/workers/configuration/cron-triggers/). Nitro automatically generates the cron triggers in the wrangler config at build time - no manual wrangler setup required.
+- **`vercel`** preset has native integration with [Vercel Cron Jobs](https://vercel.com/docs/cron-jobs). Nitro automatically generates the cron job configuration at build time - no manual `vercel.json` setup required. You can secure cron endpoints by setting the `CRON_SECRET` environment variable.
+- More presets (with native primitives support) are planned to be supported!
+
+## `waitUntil`
+When running background tasks, you might want to make sure the server or worker waits until the task is done.
+
+An optional `context.waitUntil` function <u>might</u> be available depending on the runtime.
+
+```ts
+export default defineTask({
+  run({ context }) {
+    const promise = fetch(...)
+    context.waitUntil?.(promise);
+    await promise;
+    return { result: "Success" };
+  },
+});
+```
+
+## Programmatically run tasks
+
+To manually run tasks, you can use `runTask(name, { payload?, context? })` utility from `nitro/task`.
+
+**Example:**
+
+```ts [api/migrate.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler(async (event) => {
+  // IMPORTANT: Authenticate user and validate payload!
+  const payload = Object.fromEntries(event.url.searchParams);
+  const { result } = await runTask("db:migrate", { payload });
+
+  return { result };
+});
+```
+
+### Error handling
+
+`runTask` throws an HTTP error if:
+
+- The task does not exist (status `404`).
+- The task has no handler implementation (status `501`).
+Any errors thrown inside the task's `run` function will propagate to the caller.
+
+## Run tasks with dev server
+
+Nitro's built-in dev server exposes tasks to be easily executed without programmatic usage.
+
+### Using API routes
+
+#### `/_nitro/tasks`
+
+This endpoint returns a list of available task names and their meta.
+
+```json
+// [GET] /_nitro/tasks
+{
+  "tasks": {
+    "db:migrate": {
+      "description": "Run database migrations"
+    },
+     "cms:update": {
+      "description": "Update CMS content"
+    }
+  },
+  "scheduledTasks": [
+    {
+      "cron": "* * * * *",
+      "tasks": [
+        "cms:update"
+      ]
+    }
+  ]
+}
+```
+
+#### `/_nitro/tasks/:name`
+
+This endpoint executes a task. You can provide a payload using both query parameters and body JSON payload. The payload sent in the JSON body payload must be under the `"payload"` property.
+
+<code-group>
+
+```ts [tasks/echo/payload.ts]
+export default defineTask({
+  meta: {
+    name: "echo:payload",
+    description: "Returns the provided payload",
+  },
+  run({ payload, context }) {
+    console.log("Running echo task...");
+    return { result: payload };
+  },
+});
+```
+
+```json [GET]
+// [GET] /_nitro/tasks/echo:payload?field=value&array=1&array=2
+{
+  "field": "value",
+  "array": ["1", "2"]
+}
+```
+
+```json [POST]
+/**
+ * [POST] /_nitro/tasks/echo:payload?field=value
+ * body: {
+ *   "payload": {
+ *     "answer": 42,
+ *     "nested": {
+ *       "value": true
+ *     }
+ *   }
+ * }
+ */
+{
+  "field": "value",
+  "answer": 42,
+  "nested": {
+    "value": true
+  }
+}
+```
+</code-group>
+
+> [!NOTE]
+> The JSON payload included in the body will overwrite the keys present in the query params.
+
+### Using CLI
+
+> [!IMPORTANT]
+> It is only possible to run these commands while the **dev server is running**. You should run them in a second terminal.
+
+#### List tasks
+
+```sh
+nitro task list
+```
+
+#### Run a task
+
+```sh
+nitro task run db:migrate --payload "{}"
+```
+
+The `--payload` flag accepts a JSON string that will be parsed and passed to the task. If the value is not a valid JSON object, the task runs without a payload.
+
+## Notes
+
+### Concurrency
+
+Each task can have **one running instance**. Calling a task of same name multiple times in parallel, results in calling it once and all callers will get the same return value.
+
+> [!NOTE]
+> Nitro tasks can be running multiple times and in parallel.

package/skills/nitro/docs/examples/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/skills/nitro/docs/examples/auto-imports.md

@@ -0,0 +1,93 @@
+# 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";
+import { makeGreeting } from "./server/utils/hello.ts";
+
+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/skills/nitro/docs/examples/cached-handler.md

@@ -0,0 +1,81 @@
+# Cached Handler
+
+> Cache route responses with configurable bypass logic.
+
+<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": {
+    "nitro": "latest"
+  }
+}
+```
+
+```ts [server.ts]
+import { html } from "nitro";
+import { defineCachedHandler } from "nitro/cache";
+
+export default defineCachedHandler(
+  async () => {
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    return html`
+      Response generated at ${new Date().toISOString()} (took 500ms)
+      <br />(<a href="?skipCache=true">skip cache</a>)
+    `;
+  },
+  { shouldBypassCache: ({ req }) => req.url.includes("skipCache=true") }
+);
+```
+
+```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>
+
+This example shows how to cache an expensive operation (a 500 ms delay) and conditionally bypass the cache using a query parameter. On first request, the handler executes and caches the result. Subsequent requests return the cached response instantly until the cache expires or is bypassed.
+
+## How It Works
+
+```ts [server.ts]
+import { html } from "nitro";
+import { defineCachedHandler } from "nitro/cache";
+
+export default defineCachedHandler(
+  async () => {
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    return html`
+      Response generated at ${new Date().toISOString()} (took 500ms)
+      <br />(<a href="?skipCache=true">skip cache</a>)
+    `;
+  },
+  { shouldBypassCache: ({ req }) => req.url.includes("skipCache=true") }
+);
+```
+
+The handler simulates a slow operation with a 500ms delay. As `defineCachedHandler` wraps it, the response is cached after the first execution. The `shouldBypassCache` option checks for `?skipCache=true` in the URL and when present the cache is skipped and the handler runs fresh.
+
+## Learn More
+
+- [Cache](/docs/cache)
+- [Storage](/docs/storage)

package/skills/nitro/docs/examples/custom-error-handler.md

@@ -0,0 +1,98 @@
+# Custom Error Handler
+
+> Customize error responses with a global error handler.
+
+<code-tree>
+
+```ts [error.ts]
+import { defineErrorHandler } from "nitro";
+
+export default defineErrorHandler((error, _event) => {
+  return new Response(`Custom Error Handler: ${error.message}`, {
+    status: 500,
+    headers: { "Content-Type": "text/plain" },
+  });
+});
+```
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+// import errorHandler from "./error";
+
+export default defineConfig({
+  errorHandler: "./error.ts",
+  // devErrorHandler: errorHandler,
+});
+```
+
+```json [package.json]
+{
+  "type": "module",
+  "scripts": {
+    "dev": "nitro dev",
+    "build": "nitro build"
+  },
+  "devDependencies": {
+    "nitro": "latest"
+  }
+}
+```
+
+```ts [server.ts]
+import { defineHandler, HTTPError } from "nitro";
+
+export default defineHandler(() => {
+  throw new HTTPError("Example Error!", { status: 500 });
+});
+```
+
+```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>
+
+This example shows how to intercept all errors and return a custom response format. When any route throws an error, Nitro calls your error handler instead of returning the default error page.
+
+## Error Handler
+
+Create an `error.ts` file in your project root to define the global error handler:
+
+```ts [error.ts]
+import { defineErrorHandler } from "nitro";
+
+export default defineErrorHandler((error, _event) => {
+  return new Response(`Custom Error Handler: ${error.message}`, {
+    status: 500,
+    headers: { "Content-Type": "text/plain" },
+  });
+});
+```
+
+The handler receives the thrown error and the H3 event object. You can use the event to access request details like headers, cookies, or the URL path to customize responses per route.
+
+## Triggering an Error
+
+The main handler throws an error to demonstrate the custom error handler:
+
+```ts [server.ts]
+import { defineHandler, HTTPError } from "nitro";
+
+export default defineHandler(() => {
+  throw new HTTPError("Example Error!", { status: 500 });
+});
+```
+
+When you visit the page, instead of seeing a generic error page, you'll see "Custom Error Handler: Example Error!" because the error handler intercepts the thrown error.
+
+## Learn More
+
+- [Server Entry](/docs/server-entry)