presets(vercel): support vercel queues

[RihanArfan]

🔗 Linked issue

Backport of #4127

❓ Type of change

• 📖 Documentation (updates to the documentation, readme, or JSdoc annotations)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

Implements Vercel Queue triggers support within Nitro v2 hooks (and Nuxt v4)

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nitro.build	Ready	Preview, Comment	Jun 9, 2026 2:28pm

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces Vercel Queues support to Nitro by defining queue configuration types, implementing a runtime message handler, wiring the handler into the preset, generating queue consumer functions during build, and validating the entire flow with comprehensive tests and documentation.

Changes

Vercel Queues Feature

Layer / File(s)	Summary
Queue configuration types and runtime hook signature src/presets/vercel/types.ts	Defines VercelQueueTrigger, VercelFunctionTrigger, queue options on VercelOptions, and augments NitroRuntimeHooks with the vercel:queue hook signature that receives message, metadata, and send function.
Vercel Queue dependency declaration package.json	Adds @vercel/queue (^0.1.4) to devDependencies and declares it as an optional peerDependency alongside xml2js.
Queue message handler implementation src/presets/vercel/runtime/queue-handler.ts	Implements the HTTP event handler that converts H3 events to web requests, invokes the vercel:queue hook with message and metadata, logs errors, optionally captures them via nitroApp.captureError, and rethrows to trigger retries.
Preset build-time queue handler registration src/presets/vercel/preset.ts	Adds a build:before hook that resolves @vercel/queue, throws an error if missing, and registers a lazy queue handler with configurable route and resolved runtime/queue-handler module.
Queue consumer function generation and build route management src/presets/vercel/utils.ts	Generates dedicated queue consumer .func directories with experimentalTriggers and consumer-name sanitization, prepends queue routes before ISR/catch-all rules, warns when queue config is used outside the vercel preset, and filters queue routes from observability symlinks.
Unit tests for queue preset build behavior test/unit/vercel.queues.test.ts	Tests queue consumer function directory creation (non-symlinked), experimentalTriggers emission, custom handlerRoute configuration, route entry generation in config.json, absence of routes when no triggers exist, and correct route ordering before observability catch-alls.
User documentation for Vercel Queues docs/2.deploy/20.providers/vercel.md	Documents queue topic configuration in nitro.config, message handling via the vercel:queue hook, triggering Nitro tasks based on message topics, and example code for sending messages with @vercel/queue.

---

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

---

Possibly related PRs

• nitrojs/nitro#4127: Implements the same Vercel Queues feature—queue-handler wiring, hook registration, and shared runtime/types definitions.
• nitrojs/nitro#4264: Adds local development support for Vercel Queues via vercelDev preset and queue.dev plugin, building on the same vercel:queue hook and vercel.queues.triggers configuration.
• nitrojs/nitro#4124: Modifies Vercel preset function/route generation (\.vc-config.json and manifest routes) and could interact with queue consumer route and experimentalTriggers wiring.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly relates to the changeset, explaining this is a backport implementing Vercel Queue triggers support in Nitro.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title follows conventional commits format with a scope (vercel) and descriptive subject about supporting Vercel queues, accurately reflecting the changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch backport-vercel-queues

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[RihanArfan]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

src/presets/vercel/utils.ts (1)

165-171: ⚡ Quick win

Move the new internal helper to the helper section at the end of the module.

warnUnsupportedQueues is a non-exported helper inserted between exported functions. Please keep newly added internal helpers with the rest of the private utilities at the end of the file.

As per coding guidelines, "Place non-exported/internal helpers at the end of the file".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/presets/vercel/utils.ts` around lines 165 - 171, The helper function
warnUnsupportedQueues is a non-exported internal utility and should be relocated
to the file's private helper section at the end of the module; move the entire
function (including its Nitro parameter and nitro.logger.warn call) out from
between exported functions and append it with the other non-exported helpers,
keeping the function name and behavior unchanged and updating any nearby
ordering comments if present.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/presets/vercel/utils.ts`:
- Around line 82-98: Validate the normalized handlerRoute before mutating the
filesystem: compute handlerRoute and funcDest using handlerRoute and
normalizeRouteDest (as done currently), then check whether the resolved funcDir
would equal or be inside the source bundle path (nitro.options.output.serverDir)
or otherwise collide (e.g., normalizeRouteDest("/__fallback") -> same
directory); if a collision is detected throw an explicit configuration error
indicating the invalid handlerRoute instead of proceeding to fsp.rm/fsp.cp;
perform this guard prior to any calls to fsp.rm, fsp.mkdir, or fsp.cp so the
source bundle cannot be deleted.

In `@test/unit/vercel.queues.test.ts`:
- Around line 38-51: The suite currently creates a single shared temp outDir in
beforeAll (using outDir and serverDir) which allows leftover .func folders to
leak across tests; change setup to isolate per test by moving the mkdtemp +
serverDir creation and writeFile steps into a beforeEach (or add a beforeEach
that wipes/recreates outDir) and pair it with a corresponding afterEach cleanup
(instead of afterAll) so each it gets a fresh outDir and the temporary functions
(including functions/_vercel/queues/consumer.func) cannot persist between tests;
update references to outDir/serverDir used elsewhere in the file to rely on the
per-test setup.

---

Nitpick comments:
In `@src/presets/vercel/utils.ts`:
- Around line 165-171: The helper function warnUnsupportedQueues is a
non-exported internal utility and should be relocated to the file's private
helper section at the end of the module; move the entire function (including its
Nitro parameter and nitro.logger.warn call) out from between exported functions
and append it with the other non-exported helpers, keeping the function name and
behavior unchanged and updating any nearby ordering comments if present.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 074ffddb-e7d1-49a4-a190-41b5483eb554

📥 Commits

Reviewing files that changed from the base of the PR and between f3a5773 and a18bbd3.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (7)

• docs/2.deploy/20.providers/vercel.md
• package.json
• src/presets/vercel/preset.ts
• src/presets/vercel/runtime/queue-handler.ts
• src/presets/vercel/types.ts
• src/presets/vercel/utils.ts
• test/unit/vercel.queues.test.ts