feat(vercel): queues

docs/2.deploy/20.providers/vercel.md

@@ -148,6 +148,67 @@ export default defineNitroConfig({
 
 To prevent unauthorized access to the cron handler, set a `CRON_SECRET` environment variable in your Vercel project settings. When `CRON_SECRET` is set, Nitro validates the `Authorization` header on every cron invocation.
 
+## Queues
+
+:read-more{title="Vercel Queues" to="https://vercel.com/docs/queues"}
+
+Nitro integrates with [Vercel Queues](https://vercel.com/docs/queues) to process messages asynchronously. Define your queue topics in the Nitro config and handle incoming messages with the `vercel:queue` runtime hook.
+
+```ts [nitro.config.ts]
+export default defineNitroConfig({
+  vercel: {
+    queues: {
+      triggers: [
+        { topic: "orders" },
+        { topic: "notifications" },
+      ],
+    },
+  },
+});
+```
+
+### Handling messages
+
+Use the `vercel:queue` hook in a [Nitro plugin](/guide/plugins) to process incoming queue messages:
+
+```ts [server/plugins/queues.ts]
+export default defineNitroPlugin((nitro) => {
+  nitro.hooks.hook("vercel:queue", ({ message, metadata }) => {
+    console.log(`[${metadata.topicName}] Message ${metadata.messageId}:`, message);
+  });
+});
+```
+
+### Running tasks from queue messages
+
+You can use queue messages to trigger [Nitro tasks](/tasks):
+
+```ts [server/plugins/queues.ts]
+import { runTask } from "nitro/task";
+
+export default defineNitroPlugin((nitro) => {
+  nitro.hooks.hook("vercel:queue", async ({ message, metadata }) => {
+    if (metadata.topicName === "orders") {
+      await runTask("orders:fulfill", { payload: message });
+    }
+  });
+});
+```
+
+### Sending messages
+
+Use the `@vercel/queue` package directly to send messages to a topic:
+
+```ts [server/routes/api/orders.post.ts]
+import { send } from "@vercel/queue";
+
+export default defineEventHandler(async (event) => {
+  const order = await event.req.json();
+  const { messageId } = await send("orders", order);
+  return { messageId };
+});
+```
+
 ## Custom build output configuration
 
 You can provide additional [build output configuration](https://vercel.com/docs/build-output-api/v3) using `vercel.config` key inside `nitro.config`. It will be merged with built-in auto-generated config.

docs/4.examples/vercel-queues.md

@@ -0,0 +1,192 @@
+---
+category: deploy
+icon: i-simple-icons-vercel
+---
+
+# Vercel Queues
+
+> Process background work asynchronously with Vercel Queues and Nitro tasks.
+
+<!-- automd:ui-code-tree src="../../examples/vercel-queues" default="nitro.config.ts" ignore="README.md,GUIDE.md" expandAll -->
+
+::code-tree{defaultValue="nitro.config.ts" expandAll}
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: ".",
+  experimental: {
+    tasks: true,
+  },
+  vercel: {
+    queues: {
+      triggers: [{ topic: "notifications" }],
+    },
+  },
+});
+```
+
+```json [package.json]
+{
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build"
+  },
+  "devDependencies": {
+    "@vercel/queue": "^0.1.4",
+    "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 [plugins/queue.ts]
+import { runTask } from "nitro/task";
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitro) => {
+  nitro.hooks.hook("vercel:queue", async ({ message, metadata }) => {
+    if (metadata.topicName === "notifications") {
+      await runTask("notifications:send", {
+        payload: message as Record<string, unknown>,
+      });
+    }
+  });
+});
+```
+
+```ts [routes/send.ts]
+import { send } from "@vercel/queue";
+import { defineHandler, HTTPError } from "nitro";
+
+export default defineHandler(async (event) => {
+  const body = (await event.req.json()) as Record<string, unknown>;
+  if (!body.to || !body.subject || !body.body) {
+    throw new HTTPError({
+      status: 400,
+      message: "Missing required fields `to`, `subject` or `body`",
+    });
+  }
+
+  const { messageId } = await send("notifications", {
+    to: body.to,
+    subject: body.subject,
+    body: body.body,
+  });
+  return { messageId };
+});
+```
+
+```ts [tasks/notifications/send.ts]
+import { defineTask } from "nitro/task";
+
+export default defineTask({
+  meta: {
+    description: "Send a notification",
+  },
+  async run({ payload }) {
+    console.log(`Sending notification to ${payload.to}: ${payload.subject}`);
+    return { result: "Notification sent" };
+  },
+});
+```
+
+::
+
+<!-- /automd -->
+
+<!-- automd:file src="../../examples/vercel-queues/README.md" -->
+
+Nitro integrates with [Vercel Queues](https://vercel.com/docs/queues) to process background work asynchronously.
+
+## Configuration
+
+Add queue triggers to your Nitro config. Nitro registers a queue consumer handler and makes incoming messages available via the `vercel:queue` runtime hook.
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  experimental: {
+    tasks: true,
+  },
+  vercel: {
+    queues: {
+      triggers: [{ topic: "notifications" }],
+    },
+  },
+});
+```
+
+## Sending Messages
+
+Use the `@vercel/queue` SDK to send messages to a topic from any route.
+
+```ts [routes/send.ts]
+import { send } from "@vercel/queue";
+import { defineHandler } from "nitro";
+
+export default defineHandler(async (event) => {
+  const body = await event.req.json();
+  const { messageId } = await send("notifications", {
+    to: body.to,
+    subject: body.subject,
+    body: body.body,
+  });
+  return { messageId };
+});
+```
+
+## Processing Messages
+
+Listen for the `vercel:queue` hook in a plugin to handle incoming messages. This example dispatches them to a Nitro task.
+
+```ts [plugins/queue.ts]
+import { runTask } from "nitro/task";
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitro) => {
+  nitro.hooks.hook("vercel:queue", async ({ message, metadata }) => {
+    if (metadata.topicName === "notifications") {
+      await runTask("notifications:send", {
+        payload: message as Record<string, unknown>,
+      });
+    }
+  });
+});
+```
+
+```ts [tasks/notifications/send.ts]
+import { defineTask } from "nitro/task";
+
+export default defineTask({
+  meta: {
+    description: "Send a notification",
+  },
+  async run({ payload }) {
+    console.log(`Sending notification to ${payload.to}: ${payload.subject}`);
+    return { result: "Notification sent" };
+  },
+});
+```
+
+<!-- /automd -->
+
+## Learn More
+
+- [Vercel Deployment](/deploy/providers/vercel)
+- [Tasks](/docs/tasks)

examples/vercel-queues/README.md

@@ -0,0 +1,72 @@
+Nitro integrates with [Vercel Queues](https://vercel.com/docs/queues) to process background work asynchronously.
+
+## Configuration
+
+Add queue triggers to your Nitro config. Nitro registers a queue consumer handler and makes incoming messages available via the `vercel:queue` runtime hook.
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  experimental: {
+    tasks: true,
+  },
+  vercel: {
+    queues: {
+      triggers: [{ topic: "notifications" }],
+    },
+  },
+});
+```
+
+## Sending Messages
+
+Use the `@vercel/queue` SDK to send messages to a topic from any route.
+
+```ts [routes/send.ts]
+import { send } from "@vercel/queue";
+import { defineHandler } from "nitro";
+
+export default defineHandler(async (event) => {
+  const body = await event.req.json();
+  const { messageId } = await send("notifications", {
+    to: body.to,
+    subject: body.subject,
+    body: body.body,
+  });
+  return { messageId };
+});
+```
+
+## Processing Messages
+
+Listen for the `vercel:queue` hook in a plugin to handle incoming messages. This example dispatches them to a Nitro task.
+
+```ts [plugins/queue.ts]
+import { runTask } from "nitro/task";
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitro) => {
+  nitro.hooks.hook("vercel:queue", async ({ message, metadata }) => {
+    if (metadata.topicName === "notifications") {
+      await runTask("notifications:send", {
+        payload: message as Record<string, unknown>,
+      });
+    }
+  });
+});
+```
+
+```ts [tasks/notifications/send.ts]
+import { defineTask } from "nitro/task";
+
+export default defineTask({
+  meta: {
+    description: "Send a notification",
+  },
+  async run({ payload }) {
+    console.log(`Sending notification to ${payload.to}: ${payload.subject}`);
+    return { result: "Notification sent" };
+  },
+});
+```

examples/vercel-queues/nitro.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: ".",
+  experimental: {
+    tasks: true,
+  },
+  vercel: {
+    queues: {
+      triggers: [{ topic: "notifications" }],
+    },
+  },
+});

examples/vercel-queues/package.json

@@ -0,0 +1,11 @@
+{
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build"
+  },
+  "devDependencies": {
+    "@vercel/queue": "^0.1.4",
+    "nitro": "latest"
+  }
+}

examples/vercel-queues/plugins/queue.ts

@@ -0,0 +1,12 @@
+import { runTask } from "nitro/task";
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitro) => {
+  nitro.hooks.hook("vercel:queue", async ({ message, metadata }) => {
+    if (metadata.topicName === "notifications") {
+      await runTask("notifications:send", {
+        payload: message as Record<string, unknown>,
+      });
+    }
+  });
+});

examples/vercel-queues/routes/send.ts

@@ -0,0 +1,19 @@
+import { send } from "@vercel/queue";
+import { defineHandler, HTTPError } from "nitro";
+
+export default defineHandler(async (event) => {
+  const body = (await event.req.json()) as Record<string, unknown>;
+  if (!body.to || !body.subject || !body.body) {
+    throw new HTTPError({
+      status: 400,
+      message: "Missing required fields `to`, `subject` or `body`",
+    });
+  }
+
+  const { messageId } = await send("notifications", {
+    to: body.to,
+    subject: body.subject,
+    body: body.body,
+  });
+  return { messageId };
+});