Uh oh!
There was an error while loading. Please reload this page.
refactor(nitro): use nitro v3 functionRules workflow routes - #1575
Conversation
🦋 Changeset detectedLatest commit: 2c843be The changes in this PR will be included in the next version bump. This PR includes changesets to release 17 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Uh oh!
There was an error while loading. Please reload this page.
e312e97 to
3eb081aCompare📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro | Express workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express | Nitro workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 10 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express workflow with 25 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express workflow with 50 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 10 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro workflow with 25 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express | Nitro workflow with 50 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro | Express Stream Benchmarks(includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro | Express stream pipeline with 5 transform steps (1MB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) 10 parallel streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro | Express fan-out fan-in 10 streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
|
🧪 E2E Test Results✅ All tests passed Summary
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
✅ 📋 Other
|
functionRules for workflow routesfunctionRules workflow routesUh oh!
There was an error while loading. Please reload this page.
RihanArfan
commented
Apr 24, 2026
@vercel/workflow |
VaguelySerious
left a comment
There was a problem hiding this comment.
You probably know better than me whether the nits apply, so use your judgement there. Happy to approve this once the e2e tests are running again and CI is green
VaguelySerious
left a comment
There was a problem hiding this comment.
AI review: blocking issues found
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
| * Extra esbuild options merged into every bundle this builder produces | ||
| * (steps, intermediate workflow, final workflow wrapper, webhook). | ||
| */ | ||
| esbuildOptions?: Partial<BuildOptions>; |
There was a problem hiding this comment.
AI Review: Nit
esbuildOptions: Partial<BuildOptions> is a broad surface for one knob
The new field accepts the full esbuild BuildOptions and is spread into four bundle calls with very different needs (steps: node/esm, workflow VM: neutral/cjs, webhook: node/esm, final wrapper: node/esm). The current spread order puts user options first so builder-required options like platform, format, bundle, plugins win — that's defensive — but the API still implies "you can pass any esbuild option" when in practice almost everything that matters is overridden.
Given the only consumer is sourcesContent: false, consider either narrowing the public type to a small allowlist or naming the field something closer to its actual purpose. Not blocking, but the surface area will be hard to take back later.
VaguelySerious
commented
May 2, 2026
Seems like tests are still failing, please re-ping me when they pass 👋 |
RihanArfan
commented
May 11, 2026
Hey @VaguelySerious, the related tests are passing 🥳 |
Deployment failed with the following error: |
RihanArfan
commented
May 15, 2026
@vercel/workflow |
VaguelySerious
left a comment
There was a problem hiding this comment.
AI review: no blocking issues
| }; | ||
| if (runtime) { | ||
| const webhookPath = '/.well-known/workflow/v1/webhook/**'; |
There was a problem hiding this comment.
AI Review: Note
The webhook handler is registered at /.well-known/workflow/v1/webhook/:token (line 214), but this functionRules key uses webhook/**. I built workbench/nitro-v3 with NITRO_PRESET=vercel and workflow.runtime: 'nodejs22.x' and verified that nitro's vercel preset generates two function dirs in this case:
webhook/[token].func— created viarouteFuncRouter.matchagainst the:tokenroute, gets the runtime override.webhook/[...].func— created from this**rule, also gets the runtime override.
In config.json, the webhook/(?:.*) route emitted by this rule comes before webhook/(?<token>[^/]+), so [token].func ends up unreachable. The result is a wasted function dir (extra disk/build/deploy size) and slightly looser routing (/webhook/ with no token now matches).
Suggested fix: use the same pattern as the handler, e.g. '/.well-known/workflow/v1/webhook/:token'. With matching keys, nitro reuses the single funcDir under the runtime override.
| // V2 combined: a single trigger covers both `__wkf_workflow_*` | ||
| // (workflow orchestration) and `__wkf_step_*` (step execution), | ||
| // since the same handler dispatches both. | ||
| experimentalTriggers: [WORKFLOW_QUEUE_TRIGGER], |
There was a problem hiding this comment.
AI Review: Note
The comment two lines above says "merged with any user-defined rules at the same paths so explicit user config (e.g. memory) is preserved", but the spread order here (user first, then maxDuration / experimentalTriggers) means workflow's values always win. Only fields that workflow doesn't touch (like memory) survive — user-set maxDuration, runtime, or additional experimentalTriggers get clobbered.
Two small things:
- The comment should match the behavior — something like "workflow's required triggers/maxDuration take precedence; unrelated fields like
memoryare preserved." - Other integrations (e.g.
packages/sveltekit) concatenate user triggers rather than replacing them. Probably not an issue in practice since this is a workflow-owned route, but worth deciding deliberately.
Also (related): also exercised by the E2E Vercel Prod Tests (hono) job, which currently fails on maxRetries=0 disables retries (60s timeout) on this PR while passing on main. And E2E Local Prod Tests (tanstack-start) fails on abortVoidSleepTimeoutWorkflow (also passes on main). Both look like potential regressions worth investigating before merge — they aren't in the known-flaky set.
| if (runtime) { | ||
| const webhookPath = '/.well-known/workflow/v1/webhook/**'; | ||
| rules[webhookPath] = { ...rules[webhookPath], runtime }; | ||
| } |
There was a problem hiding this comment.
AI Review: Note
runtime is propagated to the flow and webhook routes but not to the manifest route (/.well-known/workflow/v1/manifest.json, registered via addManifestHandler). If a user picks a non-default runtime, the manifest gets served from the catch-all __server function on the default runtime. Low impact (manifest is static JSON), but inconsistent — worth either documenting why it's intentionally excluded, or applying the same override.
| return majorVersion === 2; | ||
| } | ||
| return !nitro.routing; | ||
| } |
There was a problem hiding this comment.
AI Review: Note
This PR adds non-trivial new logic (isNitroV2, the useLegacyVercelBuild branch, the functionRules merge) with no unit test coverage.
Also heads-up: the existing packages/nitro/src/index.test.ts is already broken on main (2 of 10 tests reference #workflow/steps.mjs, which no longer exists since the V1→V2 combined bundle change). Not introduced by this PR, but since the file is already touching the same area, fixing those tests and adding a couple of cases for isNitroV2 and the v3-vercel branch would be a low-cost addition.
| */ | ||
| function getNitroStringExternals(nitro: Nitro): string[] | undefined { | ||
| const externals = nitro.options.externals?.external?.filter( | ||
| const external = (nitro.options as { externals?: { external?: unknown[] } }) |
There was a problem hiding this comment.
AI Review: Nit
The structural cast widens external to unknown[] then filters strings — works, but a named alias would read better:
typeNitroV2Options={externals?: {external?: unknown[]}};constexternal=(nitro.optionsasNitroV2Options).externals?.external;Non-blocking.
Uh oh!
There was an error while loading. Please reload this page.
The functionRule was keyed by `webhook/**` while the actual handler is registered at `webhook/:token`, so nitro v3's vercel preset created a second `webhook/[...].func` next to the real one and shadowed it in the generated routes. Use the same `:token` pattern as the handler so the runtime override applies to the function that actually serves traffic. Also propagate `workflow.runtime` to the public manifest route for consistency, clarify the merge-precedence comment, and refresh the unit tests to cover the v3 functionRules path and the `isNitroV2` detection. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Peter Wielander <peter.wielander@vercel.com>
VaguelySerious
commented
May 20, 2026
auto-merge is on, waiting for CI to pass |
| enhanced-resolve: 5.19.0 | ||
| esbuild: ^0.27.3 | ||
| nitro: 3.0.1-alpha.1 | ||
| nitro: ^3.0.260429-beta |
There was a problem hiding this comment.
Should nitro on the workbench not be a stable release? 🤔
There was a problem hiding this comment.
Nitro v2 is nitropack and Nitro v3 is nitro so I think it should be fine. Most the things target Nitro v3 although it's not got a "stable" release yet till Nuxt v5.
No backport to This commit refactors To override, re-run the Backport to stable workflow manually via |
Description
Currently we separately build the Workflows functions for the Vercel Build Output API when deploying a Nitro app to Vercel. This means the Workflows routes aren't part of the Nitro bundle.
This PR changes to now handle the Workflows routes as handlers within Nitro v3. Nitro v2 is untouched.
How did you test your changes?
Locally ran
nitro devin thenitro-v3workspace and visited the API routePOST /api/test-direct-step-call.PR Checklist - Required to merge
pnpm changesetwas run to create a changelog for this PRpnpm changeset --emptyif you are changing documentation or workbench appsgit commit --signoffon your commits)@vercel/workflowin a comment once the PR is ready, and the above checklist is complete