refactor(nitro): use nitro v3 functionRules workflow routes#1575
Open
RihanArfan wants to merge 10 commits into
Open
refactor(nitro): use nitro v3 functionRules workflow routes#1575RihanArfan wants to merge 10 commits into
functionRules workflow routes#1575RihanArfan wants to merge 10 commits into
Conversation
|
Contributor
pi0
reviewed
Apr 2, 2026
RihanArfan
force-pushed
the
feat/nitro-builder-improvement
branch
from
e312e97 to
3eb081a
Compare
Contributor
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
workflow with 1 step💻 Local Development
▲ Production (Vercel)
workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
workflow with 10 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
workflow with 25 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
workflow with 50 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
workflow with 10 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
workflow with 25 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
workflow with 50 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
Stream Benchmarks (includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
stream pipeline with 5 transform steps (1MB)💻 Local Development
▲ Production (Vercel)
10 parallel streams (1MB each)💻 Local Development
▲ Production (Vercel)
fan-out fan-in 10 streams (1MB each)💻 Local Development
▲ Production (Vercel)
SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
❌ Some benchmark jobs failed:
Check the workflow run for details. |
Contributor
🧪 E2E Test Results✅ All tests passed Summary
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
✅ 📋 Other
|
RihanArfan
changed the title
functionRules for workflow routesfunctionRules workflow routes
RihanArfan
changed the title
functionRules workflow routesfunctionRules workflow routes
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
Member
Author
|
@vercel/workflow |
Member
VaguelySerious
left a comment
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
Member
VaguelySerious
left a comment
VaguelySerious
left a comment
There was a problem hiding this comment.
AI review: blocking issues found
| * Extra esbuild options merged into every bundle this builder produces | ||
| * (steps, intermediate workflow, final workflow wrapper, webhook). | ||
| */ | ||
| esbuildOptions?: Partial<BuildOptions>; |
Member
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.
Member
|
Seems like tests are still failing, please re-ping me when they pass 👋 |
Member
Author
|
Hey @VaguelySerious, the related tests are passing 🥳 |
Contributor
|
Deployment failed with the following error: |
Member
Author
|
@vercel/workflow |
Member
VaguelySerious
left a comment
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/**'; |
Member
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], |
Member
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 }; | ||
| } |
Member
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; | ||
| } |
Member
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[] } }) |
Member
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:
type NitroV2Options = { externals?: { external?: unknown[] } };
const external = (nitro.options as NitroV2Options).externals?.external;Non-blocking.
| // removed the `experimental.tsconfigPaths` opt-in in 3.0.260415-beta+. | ||
| resolve: { | ||
| alias: { | ||
| '@repo': fileURLToPath(new URL('../../', import.meta.url)), |
Member
There was a problem hiding this comment.
AI Review: Nit
I searched workbench/vite/ (including the symlinked workflows/ and plugins/ dirs) and didn't find any @repo/... imports. If the alias is preventative for future imports, fine — but if not, this can probably be dropped. Aliasing to the entire repo root is broad and a bit surprising for a workbench.
VaguelySerious
approved these changes
May 19, 2026
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
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.
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