feat(vercel): queues (#4127)

Author: RihanArfan

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

@@ -148,6 +148,68 @@ export default defineConfig({
 
 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: [
+        // Only `topic` is required
+        { topic: "notifications" },
+        { topic: "orders", retryAfterSeconds: 60, initialDelaySeconds: 5 },
+      ],
+    },
+  },
+});
+```
+
+### 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, send }) => {
+    console.log(`[${metadata.topicName}] Message ${metadata.messageId}:`, message);
+  });
+});
+```
+
+### Running tasks from queue messages
+
+You can use queue messages to trigger [Nitro tasks](/docs/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.

package.json

@@ -107,6 +107,7 @@
     "@types/semver": "^7.7.1",
     "@types/xml2js": "^0.4.14",
     "@typescript/native-preview": "^7.0.0-dev.20260413.1",
+    "@vercel/queue": "^0.1.4",
     "@vitest/coverage-v8": "^4.1.4",
     "automd": "^0.4.3",
     "c12": "^4.0.0-beta.4",
@@ -174,6 +175,7 @@
     "zephyr-agent": "^1.0.1"
   },
   "peerDependencies": {
+    "@vercel/queue": "^0.1.4",
     "dotenv": "*",
     "giget": "*",
     "jiti": "^2.6.1",
@@ -183,6 +185,9 @@
     "zephyr-agent": "^0.2.0"
   },
   "peerDependenciesMeta": {
+    "@vercel/queue": {
+      "optional": true
+    },
     "dotenv": {
       "optional": true
     },

pnpm-lock.yaml

@@ -2,13 +2,16 @@ import { defineNitroPreset } from "../_utils/preset.ts";
 import type { Nitro } from "nitro/types";
 import { presetsDir } from "nitro/meta";
 import { join } from "pathe";
+import { importDep } from "../../utils/dep.ts";
 import {
   deprecateSWR,
   generateFunctionFiles,
   generateStaticFiles,
   resolveVercelRuntime,
 } from "./utils.ts";
 
+import type { VercelFunctionTrigger } from "./types.ts";
+
 export type { VercelOptions as PresetOptions } from "./types.ts";
 
 // https://vercel.com/docs/build-output-api/v3
@@ -65,6 +68,35 @@ const vercel = defineNitroPreset(
             handler: join(presetsDir, "vercel/runtime/cron-handler"),
           });
         }
+
+        // Queue consumer handler
+        const queues = nitro.options.vercel?.queues;
+        if (queues?.triggers?.length) {
+          await importDep({
+            id: "@vercel/queue",
+            dir: nitro.options.rootDir,
+            reason: "Vercel Queues",
+          });
+
+          const handlerRoute = queues.handlerRoute || "/_vercel/queues/consumer";
+
+          nitro.options.handlers.push({
+            route: handlerRoute,
+            lazy: true,
+            handler: join(presetsDir, "vercel/runtime/queue-handler"),
+          });
+
+          const queueTriggers: VercelFunctionTrigger[] = queues.triggers.map(
+            ({ topic, ...opts }) => ({ type: "queue/v2beta", topic, ...opts })
+          );
+          nitro.options.vercel ??= {};
+          nitro.options.vercel.functionRules ??= {};
+          const existingRule = nitro.options.vercel.functionRules[handlerRoute];
+          nitro.options.vercel.functionRules[handlerRoute] = {
+            ...existingRule,
+            experimentalTriggers: [...(existingRule?.experimentalTriggers || []), ...queueTriggers],
+          };
+        }
       },
       "rollup:before": (nitro: Nitro) => {
         deprecateSWR(nitro);

src/presets/vercel/preset.ts

@@ -0,0 +1,15 @@
+import { handleCallback, send } from "@vercel/queue";
+import { defineHandler } from "nitro";
+import { useNitroApp, useNitroHooks } from "nitro/app";
+
+export default defineHandler((event) => {
+  return handleCallback(async (message, metadata) => {
+    try {
+      await useNitroHooks().callHook("vercel:queue", { message, metadata, send });
+    } catch (error) {
+      console.error("[vercel:queue]", error);
+      useNitroApp().captureError?.(error as Error, { event, tags: ["vercel:queue"] });
+      throw error;
+    }
+  })(event.req as Request);
+});

src/presets/vercel/runtime/queue-handler.ts

@@ -1,3 +1,5 @@
+import type { send } from "@vercel/queue";
+
 /**
  * Vercel Build Output Configuration
  * @see https://vercel.com/docs/build-output-api/v3
@@ -105,9 +107,22 @@ export interface VercelServerlessFunctionConfig {
    */
   runtime?: "nodejs20.x" | "nodejs22.x" | "bun1.x" | (string & {});
 
+  /**
+   * Experimental trigger configuration (e.g., Vercel Queues).
+   */
+  experimentalTriggers?: VercelFunctionTrigger[];
+
   [key: string]: unknown;
 }
 
+export type VercelFunctionTrigger = {
+  type: "queue/v2beta";
+  topic: string;
+  retryAfterSeconds?: number;
+  initialDelaySeconds?: number;
+  consumer?: string;
+};
+
 export interface VercelOptions {
   config?: VercelBuildConfigV3;
 
@@ -148,6 +163,48 @@ export interface VercelOptions {
    */
   cronHandlerRoute?: string;
 
+  /**
+   * Vercel Queues configuration.
+   *
+   * Messages are delivered via the `vercel:queue` runtime hook.
+   *
+   * @example
+   * ```ts
+   * // nitro.config.ts
+   * export default defineNitroConfig({
+   *   vercel: {
+   *     queues: {
+   *       triggers: [{ topic: "orders" }],
+   *     },
+   *   },
+   * });
+   * ```
+   *
+   * ```ts
+   * // server/plugins/queues.ts
+   * export default defineNitroPlugin((nitro) => {
+   *   nitro.hooks.hook("vercel:queue", ({ message, metadata }) => {
+   *     console.log(`Received message on ${metadata.topicName}:`, message);
+   *   });
+   * });
+   * ```
+   *
+   * @see https://vercel.com/docs/queues
+   */
+  queues?: {
+    /**
+     * Route path for the queue consumer handler.
+     * @default "/_vercel/queues/consumer"
+     */
+    handlerRoute?: string;
+    /** Queue topic triggers to subscribe to. */
+    triggers: Array<{
+      topic: string;
+      retryAfterSeconds?: number;
+      initialDelaySeconds?: number;
+    }>;
+  };
+
   /**
    * Per-route function configuration overrides.
    *
@@ -206,3 +263,13 @@ export type PrerenderFunctionConfig = {
    */
   exposeErrBody?: boolean;
 };
+
+declare module "nitro/types" {
+  export interface NitroRuntimeHooks {
+    "vercel:queue": (_: {
+      message: unknown;
+      metadata: import("@vercel/queue").MessageMetadata;
+      send: typeof send;
+    }) => void;
+  }
+}

src/presets/vercel/types.ts

@@ -63,7 +63,7 @@ export async function generateFunctionFiles(nitro: Nitro) {
   ) {
     nitro.logger.warn(
       "`experimentalTriggers` on the base `vercel.functions` config applies to the catch-all function and is likely not what you want. " +
-        "Routes with queue triggers are not accesible on the web." +
+        "Routes with queue triggers are not accessible on the web. " +
         "Use `vercel.functionRules` to attach triggers to specific routes instead."
     );
   }
@@ -72,9 +72,9 @@ export async function generateFunctionFiles(nitro: Nitro) {
   await writeFile(functionConfigPath, JSON.stringify(baseFunctionConfig, null, 2));
 
   const functionRules = nitro.options.vercel?.functionRules;
-  const hasfunctionRules = functionRules && Object.keys(functionRules).length > 0;
+  const hasRouteFunctionConfig = functionRules && Object.keys(functionRules).length > 0;
   let routeFuncRouter: Router<VercelServerlessFunctionConfig> | undefined;
-  if (hasfunctionRules) {
+  if (hasRouteFunctionConfig) {
     routeFuncRouter = new Router<VercelServerlessFunctionConfig>();
     routeFuncRouter._update(
       Object.entries(functionRules).map(([route, data]) => ({
@@ -128,7 +128,7 @@ export async function generateFunctionFiles(nitro: Nitro) {
 
   // Write functionRules custom function directories
   const createdFuncDirs = new Set<string>();
-  if (hasfunctionRules) {
+  if (hasRouteFunctionConfig) {
     for (const [pattern, overrides] of Object.entries(functionRules!)) {
       const funcDir = resolve(
         nitro.options.output.serverDir,