feat(vercel): support queues in local dev #4264
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| import type { Nitro } from "nitro/types"; | ||
| import { presetsDir } from "nitro/meta"; | ||
| import { resolveModulePath } from "exsolve"; | ||
|
|
||
| /** | ||
| * Configure local development emulation for the Vercel preset. | ||
| * | ||
| * When `vercel.queues.triggers` is configured, propagates the trigger list | ||
| * to runtime config and injects a runtime plugin that binds each topic to | ||
| * the `vercel:queue` hook through env-runner's queue dev bridge. | ||
| * | ||
| */ | ||
| export async function vercelDevModule(nitro: Nitro) { | ||
| if (!nitro.options.dev) { | ||
| return; | ||
| } | ||
|
|
||
| const triggers = nitro.options.vercel?.queues?.triggers; | ||
| if (!triggers?.length) { | ||
| return; | ||
| } | ||
|
|
||
| if (nitro.options.devServer.runner !== "vercel") { | ||
| throw new Error( | ||
| `[vercel:queue] Local queue delivery requires the \`vercel\` dev runner, but \`devServer.runner\` is set to "${nitro.options.devServer.runner}". Remove the \`devServer.runner\` override in your \`nitro.config.ts\` or set it explicitly to \`"vercel"\`.` | ||
| ); | ||
| } | ||
|
|
||
| // Propagate triggers to the runtime plugin via runtimeConfig. | ||
| nitro.options.runtimeConfig.vercel = { | ||
| ...nitro.options.runtimeConfig.vercel, | ||
| queues: { | ||
| triggers: triggers.map((t) => ({ ...t })), | ||
| }, | ||
| }; | ||
|
|
||
| nitro.options.plugins = nitro.options.plugins || []; | ||
| nitro.options.plugins.unshift( | ||
| resolveModulePath("./vercel/runtime/queue.dev", { | ||
| from: presetsDir, | ||
| extensions: [".mjs", ".ts"], | ||
| }) | ||
| ); | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,57 @@ | ||||||
| import { send } from "@vercel/queue"; | ||||||
| import type { MessageMetadata } from "@vercel/queue"; | ||||||
| import type { NitroAppPlugin } from "nitro/types"; | ||||||
| import { useRuntimeConfig } from "nitro/runtime-config"; | ||||||
| import { registerVercelQueueConsumer } from "env-runner/runners/vercel/queue-dev"; | ||||||
|
|
||||||
| interface DevTrigger { | ||||||
| topic: string; | ||||||
| retryAfterSeconds?: number; | ||||||
| initialDelaySeconds?: number; | ||||||
| } | ||||||
|
|
||||||
| const queueDevPlugin: NitroAppPlugin = (nitroApp) => { | ||||||
| const triggers = | ||||||
| (useRuntimeConfig() as { vercel?: { queues?: { triggers?: DevTrigger[] } } }).vercel?.queues | ||||||
| ?.triggers || []; | ||||||
|
|
||||||
| if (triggers.length === 0) { | ||||||
| return; | ||||||
| } | ||||||
|
|
||||||
| const unregisters: Array<() => void> = []; | ||||||
|
|
||||||
| for (const trigger of triggers) { | ||||||
| const unregister = registerVercelQueueConsumer({ | ||||||
| topic: trigger.topic, | ||||||
| retryAfterSeconds: trigger.retryAfterSeconds, | ||||||
| handler: async (message: unknown, metadata: unknown) => { | ||||||
| try { | ||||||
| await nitroApp.hooks.callHook("vercel:queue", { | ||||||
| message, | ||||||
| metadata: metadata as MessageMetadata, | ||||||
| send, | ||||||
| }); | ||||||
| } catch (error) { | ||||||
| console.error("[vercel:queue]", error); | ||||||
|
Contributor
There was a problem hiding this comment. 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win Use Nitro/consola logger instead of Switch this to Suggested diff- console.error("[vercel:queue]", error);
+ nitroApp.logger.error("[vercel:queue]", error);As per coding guidelines 📝 Committable suggestion
Suggested change
🤖 Prompt for AI Agents |
||||||
| nitroApp.captureError?.(error as Error, { | ||||||
| tags: ["vercel:queue"], | ||||||
| }); | ||||||
| // Rethrow so @vercel/queue schedules a local retry. | ||||||
| throw error; | ||||||
| } | ||||||
| }, | ||||||
| }); | ||||||
| unregisters.push(unregister); | ||||||
| } | ||||||
|
|
||||||
| nitroApp.hooks.hook("close", () => { | ||||||
| for (const unregister of unregisters) { | ||||||
| try { | ||||||
| unregister(); | ||||||
| } catch {} | ||||||
| } | ||||||
| }); | ||||||
| }; | ||||||
|
|
||||||
| export default queueDevPlugin; | ||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🧩 Analysis chain
🏁 Script executed:
Repository: nitrojs/nitro
Length of output: 30841
🏁 Script executed:
Repository: nitrojs/nitro
Length of output: 228
🌐 Web query:
env-runner npm package runners/vercel/queue-dev💡 Result:
The string “env-runner npm package runners/vercel/queue-dev” doesn’t resolve cleanly to a specific, documented npm package path or file name in the sources I found. What I could confirm: 1) The npm package “env-runner” (unjs/env-runner) exists and provides “runners” including a Vercel runner at the import path env-runner/runners/vercel (not “queue-dev”). It also documents that it can run across multiple environments/runtimes and exposes a Vercel runner that simulates a Vercel deployment environment with Vercel-like header injection. [1][2] 2) Vercel-specific behavior for env-runner is implemented via “VercelEnvRunner”. Its changes include injection of Vercel-related request headers such as x-vercel-deployment-url and x-vercel-id, and it sets process.env values like VERCEL, VERCEL_ENV, VERCEL_REGION, and NOW_REGION in the worker context. [3][4] 3) Vercel Queues are a separate Vercel product (queues durable event streaming). Vercel’s own docs describe authentication and API behavior for Queues, but those docs don’t mention an env-runner “queue-dev” runner. [5][6] If you meant something else by “queue-dev” (for example, a specific file/directory name inside env-runner like runners/vercel/queue-dev, or a tag/example used for local queue development), tell me one of the following and I can re-search precisely: - the full npm package name (including scope/version) you intend, or - the exact GitHub file path you saw (repo + path), or - a snippet of the import/require statement you’re using. Citations: - env-runner README shows available runners and explicitly includes VercelEnvRunner at env-runner/runners/vercel and describes Vercel context/header injection. [1] - env-runner repository overview similarly lists Vercel runner and its purpose. [2] - env-runner commit implementing Vercel env var + header injection (VercelEnvRunner). [3] - env-runner commit adding VERCEL_DEPLOYMENT_ID and testing it in VercelEnvRunner. [4] - Vercel Queues docs (product/API) don’t reference env-runner “queue-dev”. [5][6]
Citations:
🌐 Web query:
registerVercelQueueConsumer env-runner function💡 Result:
There is no documented function named registerVercelQueueConsumer in either the Vercel Queues SDK/docs or the unjs/env-runner project docs. What you likely want (Vercel Queues “push-mode” consumer registration): 1) Configure your consumer endpoint trigger in vercel.json using a queue/v2beta experimentalTriggers entry for your route. Vercel invokes that route automatically in push mode. [1][2][3] Example: { "functions": { "app/api/queues/process-order/route.ts": { "experimentalTriggers": [{ "type": "queue/v2beta", "topic": "orders" }] } } } 2) Export your handler using
@vercel/queue’s handleCallback (or handleNodeCallback for certain routers). Messages are acknowledged when your handler completes and retried if the handler throws. [4][3][5] Example: import { handleCallback } from '@vercel/queue'; export const POST = handleCallback(async (message, metadata) => { await processOrder(message); }); How unjs/env-runner fits in: - env-runner is a generic runtime “environment runner” (it can simulate Vercel via VercelEnvRunner), but its docs don’t mention any Vercel Queue consumer registration helper like registerVercelQueueConsumer. [6][7] - So, in practice, you would still register a Vercel Queues consumer the Vercel way (vercel.json trigger + handleCallback handler), while env-runner may help simulate the Vercel runtime environment during local testing. [6][7][5] If you can share where you saw “registerVercelQueueConsumer” (repo/package/link or the relevant file), I can pinpoint whether it’s from a different library or an internal wrapper and map it to the equivalent Vercel Queues APIs.Citations:
🏁 Script executed:
Repository: nitrojs/nitro
Length of output: 2055
Critical: unresolved
env-runner/runners/vercel/queue-devimport pathThis import does not exist in the
env-runnerpackage. The package providesenv-runner/runners/vercelbut not aqueue-devsubpath, andregisterVercelQueueConsumeris not an exported function. Verify the correct import path and function name.Additionally:
console.errorwithconsola.error(required forsrc/presets/**)🧰 Tools
🪛 GitHub Check: tests-checks (ubuntu-latest)
[failure] 5-5:
Cannot find module 'env-runner/runners/vercel/queue-dev' or its corresponding type declarations.
🤖 Prompt for AI Agents